PD-280 — Alignement canonique de l'etat PENDING pour la verification de preuve (v3 corrigee)¶

0. Traceabilite des corrections (ecarts -> corrections)¶

1. Objectif¶

Definir contractuellement l'introduction de l'etat PENDING dans la verification de preuve, de maniere coherente entre: - le modele metier (CheckResult), - le contrat API de verification, - les invariants de finalisation, - et les artefacts formels TLA+.

La specification impose une distinction testable entre: - PENDING (transitoire, sous SLA), - INDETERMINATE (absence de conclusion potentiellement durable).

2. Perimetre / Hors perimetre¶

Inclus¶

• Extension de CheckResult a 4 valeurs: OK | KO | INDETERMINATE | PENDING.
• Introduction du statut global de job: verificationStatus: PENDING | DONE.
• Introduction de verificationRequestId (UUID technique) pour identifier une verification.
• Contrat API de verification avec linkResults nullable pour maillons en cours.
• Regles de coherence entre verificationStatus, linkResults, pendingReason, nextCheckAfterSeconds.
• Reevaluation SLA lazy declenchee lors de l'appel API de verification.
• Alignement TLA+ (CheckResults, RealStates, ASSUME) et mapping norm.yaml.
• Preservation de l invariant de finalisation: aucun maillon PENDING apres finalisation.

Exclu¶

• Pattern asynchrone complet de verification (queue/BullMQ) - hors perimetre.
• Worker/cron de reevaluation SLA - hors perimetre (mode lazy uniquement).
• Changement de l endpoint de creation de preuve - hors perimetre.
• Changement de la logique metier de finalisation de preuve - hors perimetre.
• Toute regle non testable est hors perimetre de cette story.
• Invariants constitutionnels transversaux (ex: chiffrement at-rest, HSM/KMS): non repetes ici, appliques par defaut.

3. Definitions¶

• CheckResult: resultat de verification d un maillon (OK, KO, INDETERMINATE, PENDING) en representation interne.
• verificationStatus: etat global du job de verification (PENDING, DONE) expose API.
• verificationRequestId: UUID v4 technique, porte par la reponse, identifiant la verification materialisee cote serveur.
• PENDING: verification en cours, issue attendue dans un delai borne.
• INDETERMINATE: verification impossible a conclure, potentiellement durable.
• linkResults: dictionnaire des resultats par maillon en API; null = maillon en cours.
• proof_finalized: indicateur metier de finalisation de preuve.
• SLA: borne temporelle contractuelle de resolution d un maillon PENDING.

4. Invariants (non negociables)¶

5. Modele de donnees et flux nominaux¶

5.1 Formats et contraintes de donnees (source unique de verite)¶

Regles de coherence supplementaires: - verificationRequestId est obligatoire sur toute reponse 200. - Si verificationStatus = DONE, alors aucune valeur linkResults[*] ne peut etre null. - Si verificationStatus = PENDING, au moins une valeur linkResults[*] est null. - Si verificationStatus = PENDING, pendingReason et nextCheckAfterSeconds sont obligatoires. - Si verificationStatus = DONE, pendingReason et nextCheckAfterSeconds sont absents.

5.2 SLA temporels (transitions avec temporalite)¶

Regle de perimetre: - Aucun worker/cron background n est requis ni autorise par cette story pour la reevaluation SLA.

5.3 Machine a etats et transitions retour¶

• Etat job PENDING (pour un verificationRequestId)
• PENDING -> DONE: AUTORISEE (condition: tous linkResults[*] exposes sont resolves dans {OK,KO,INDETERMINATE}).
• PENDING -> PENDING: AUTORISEE (polling tant que condition de completion non atteinte).
• Etat job DONE (terminal pour ce verificationRequestId)

• DONE -> *: INTERDITE pour ce verificationRequestId.

• Etat maillon PENDING (interne)

• PENDING -> OK|KO|INDETERMINATE: AUTORISEE.
• Etat maillon OK (terminal)
• OK -> *: INTERDITE.
• Etat maillon KO (terminal)
• KO -> *: INTERDITE.
• Etat maillon INDETERMINATE (terminal)
• INDETERMINATE -> *: INTERDITE.

Regles idempotentes d appel: - L endpoint de verification est lecture seule (aucune mutation metier creee par l appel). - Si un resultat DONE existe deja pour le proofId dans ce perimetre, l endpoint retourne cette reponse DONE a l identique (y compris verificationRequestId), sans transition retour. - Deux appels concurrents pour le meme proofId doivent observer le meme resultat.

5.4 Strategie migration DDL (si colonne existante impactee)¶

5.5 Atomicite multi-composant¶

Aucune atomicite multi-composant additionnelle introduite par cette story (pas de nouveau flux DB + queue/append-only dans le perimetre).
Statut: Aucune contrainte additionnelle applicable dans ce perimetre.

5.6 Contraintes inter-modules¶

Interaction identifiee: dependance potentielle avec la logique de gel/integrite (PD-251) consommatrice de CheckResult.
Contrat: - Ce changement n autorise pas de contournement des guards d integrite existants. - Toute regle cross-module doit traiter explicitement PENDING comme non-final. - Aucune nouvelle route cross-module ajoutee dans ce perimetre.

5.7 Mapping interne/API (frontiere explicite)¶

• Representation interne:
• CheckResult peut prendre PENDING.
• Representation API:
• linkResults[*] = null represente un maillon interne PENDING.
• verificationStatus expose PENDING ou DONE au niveau job.
• Regle de conversion obligatoire:
• Le code de mapping DTO convertit systematiquement CheckResult.PENDING -> null dans linkResults.
• La valeur litterale "PENDING" ne doit jamais etre exposee dans linkResults[*] cote API publique.

5.8 Diagrammes Mermaid¶

5.8.1 Machine a etats — Maillon (CheckResult interne)¶

Chaque maillon suit une machine a etats monotone a 4 valeurs (INV-280-05). PENDING est le seul etat non-terminal. La transition PENDING -> INDETERMINATE peut etre declenchee par expiration SLA lazy (INV-280-04, ERR-280-05).

stateDiagram-v2
    [*] --> PENDING : creation maillon

    PENDING --> OK : verification reussie
    PENDING --> KO : verification echouee
    PENDING --> INDETERMINATE : echec durable\nou expiration SLA lazy\n(pendingResolutionTtl depasse)

    OK --> [*] : terminal (INV-280-05)
    KO --> [*] : terminal (INV-280-05)
    INDETERMINATE --> [*] : terminal (INV-280-05)

    note right of PENDING
        Si proof_finalized = TRUE,
        PENDING interdit (INV-280-04)
    end note

5.8.2 Machine a etats — Job de verification (verificationStatus)¶

Le job de verification est identifie par verificationRequestId (INV-280-06). L etat DONE est terminal et idempotent (INV-280-09).

stateDiagram-v2
    [*] --> PENDING : premier appel verification

    PENDING --> PENDING : polling\n(maillons non tous resolus)
    PENDING --> DONE : tous linkResults\ndans {OK, KO, INDETERMINATE}\n(INV-280-02)

    DONE --> [*] : terminal (INV-280-06)

    note right of DONE
        Tout rappel pour le meme proofId
        retourne la reponse DONE identique
        (idempotence, INV-280-06 / INV-280-09)
    end note

    note left of PENDING
        pendingReason + nextCheckAfterSeconds
        obligatoires (INV-280-03)
    end note

5.8.3 Sequence — Flux de verification de preuve (appel API)¶

Interactions entre le client, l endpoint de verification, la couche metier et la base de donnees. Couvre le flux nominal PENDING, la reevaluation SLA lazy et le mapping interne/API (§5.7).

sequenceDiagram
    participant Client
    participant API as Endpoint Verification
    participant Service as Service Metier
    participant DB as PostgreSQL

    Client->>API: GET /proofs/{proofId}/verify
    API->>API: Validation proofId UUID v4<br/>(ERR-280-01 si invalide)

    API->>DB: SELECT verification existante<br/>par proofId
    alt Verification DONE existante (INV-280-06)
        DB-->>API: verificationRequestId + resultat DONE
        API-->>Client: 200 { verificationStatus: DONE,<br/>linkResults: {OK|KO|INDETERMINATE},<br/>verificationRequestId }
    else Verification PENDING ou nouvelle
        DB-->>Service: maillons + timestamps

        loop Pour chaque maillon PENDING
            Service->>Service: Lecture etat maillon<br/>(resolution externe, INV-280-09)
            alt pendingResolutionTtl depasse
                Service->>Service: Reclassification lazy<br/>PENDING -> INDETERMINATE<br/>(ERR-280-05)
            end
        end

        Service->>Service: Calcul verificationStatus<br/>(INV-280-02)

        alt Tous maillons resolus
            Service->>DB: Persister DONE +<br/>verificationRequestId
            Service->>API: verificationStatus = DONE
        else Maillons encore PENDING
            Service->>API: verificationStatus = PENDING<br/>+ pendingReason<br/>+ nextCheckAfterSeconds<br/>(INV-280-03)
        end

        API->>API: Mapping CheckResult.PENDING -> null<br/>dans linkResults (§5.7)
        API->>API: Clamp nextCheckAfterSeconds<br/>[1,86400] (§5.2)
        API-->>Client: 200 { verificationRequestId,<br/>verificationStatus,<br/>linkResults, ... }
    end

6. Cas d erreur¶

7. Criteres d acceptation (testables)¶

8. Scenarios de test (Given / When / Then)¶

• SCN-280-01 (pending nominal)
• Given une preuve avec BLOCKCHAIN_ANCHOR non finalise
• When le client appelle l endpoint de verification

• Then verificationRequestId est present (UUID v4), verificationStatus = PENDING, linkResults.BLOCKCHAIN_ANCHOR = null, pendingReason present, nextCheckAfterSeconds dans [1,86400]

• SCN-280-02 (done nominal)

• Given une preuve avec tous maillons verifies
• When le client appelle l endpoint

• Then verificationStatus = DONE, aucun linkResults[*] = null, pendingReason absent, nextCheckAfterSeconds absent

• SCN-280-03 (reclassification finality)

• Given un batch en PENDING_FINALITY
• When verification du maillon blockchain

• Then resultat maillon interne = PENDING (jamais INDETERMINATE) et exposition API en null

• SCN-280-04 (indeterminate durable)

• Given blockchain inaccessible
• When verification echoue sans perspective de resolution courte

• Then resultat maillon = INDETERMINATE

• SCN-280-05 (expiration SLA lazy)

• Given un maillon est PENDING et son pendingResolutionTtl est depasse
• When un appel API de verification est recu (declencheur lazy)

• Then le maillon est reclassifie INDETERMINATE pendant le traitement de la reponse, sans worker background

• SCN-280-06 (invariant finalisation)

• Given proof_finalized = TRUE
• When on lit les linkResults

• Then aucune valeur PENDING ni null n est autorisee

• SCN-280-07 (validation format proofId)

• Given un proofId non UUID v4
• When appel endpoint

• Then 400 Bad Request avec code INVALID_PROOF_ID

• SCN-280-08 (alignement TLA+)

• Given CheckResults et RealStates
• When la verification formelle est lancee

• Then RealStates = CheckResults et ASSUME satisfait

• SCN-280-09 (bornes pendingResolutionTtl)

• Given pendingResolutionTtl configurable
• When la configuration vaut min=1h, max=30j, puis valeurs hors bornes

• Then les bornes contractuelles sont appliquees et testees (acceptation aux bornes, rejet/normalisation hors bornes selon mecanisme de config)

• SCN-280-10 (concurrence idempotente)

• Given deux appels concurrents au meme proofId
• When les deux appels sont traites en parallele
• Then les deux reponses sont identiques sur le resultat metier observable; aucune mutation due a l appel de verification

9. Hypotheses explicites¶

10. Contraintes techniques et points a clarifier¶

10.1 Contraintes techniques (stack reelle)¶

• Projet cible: ProbatioVault-backend.
• Stack contractuelle: NestJS + TypeORM + PostgreSQL (interdiction de referencer une autre stack).
• Artefacts impactes: code metier backend, contrats API, tests backend, fichiers TLA+ associes, norm.yaml.
• Compatibilite backward: les consumers API doivent supporter la semantique PENDING (via null dans linkResults et verificationStatus).

10.2 Points a clarifier (donnees manquantes)¶

1. Taxonomie definitive de pendingReason (liste exhaustive ou extensible) non fournie.
2. Politique officielle de versionnement API pour l ajout de nouvelle valeur enum non fournie.
3. Exigence explicite de comportement client legacy face a PENDING non fournie.
4. Strategie de down migration acceptee en production (en cas de presence de donnees PENDING) non tranchee.

References¶

• Epic parent : PD-217 — LEGAL & COMPLIANCE
• JIRA : PD-280
• Repos concernes : ProbatioVault-backend, ProbatioVault-doc
• Documents associes : PV_Proof.tla, _AnchoredFacts_PROOF.tla, norm.yaml, RFC PV-PROOF, learnings PD-40, PD-86