PD-286 — Livrable agent export-state-machine-backend (C4)¶

Story : Export probatoire multi-volumes (>768 MB jusqu'à 10 GB) Module : export-state-machine-backend (C4) — backend NestJS + TypeORM + PostgreSQL Wave : 1 (foundations) — pas de dépendance amont Agent : agent-developer (Claude)

1. Périmètre traité¶

Implémentation stricte du contrat C4 (cf. PD-286-code-contracts.yaml) :

• ExportSession (entity TypeORM) — persistance d'une session d'export.
• ExportStateMachine (service stateless) — matrice de transitions exhaustive (spec §4).
• ExpiredExportWorker — cron 30 s * (non terminal) → EXPIRED quand expires_at < now(), mono-instance via pg_try_advisory_lock.
• Migration *-pd286-export-multi-volumes — type ENUM PostgreSQL export_state_enum, table vault_secure.export_sessions, trigger fail-closed prevent_forbidden_export_transition, trigger updated_at, index, constraints CHECK.
• Constantes (VOLUME_MAX_BYTES, MAX_TOTAL_EXPORT_BYTES, TTL bornes, tick worker, advisory lock key) ajoutées à export.constants.ts.
• Wiring ExportModule (entité + providers + export ExportStateMachine pour les modules consommateurs C5/C6).

Hors périmètre (autres agents step 6b) : C1 partitioner, C2 DTO, C3 manifest builder, C5 controller, C6 audit, C7-C10 app, C11 tests.

2. Fichiers livrés¶

Aucun fichier hors src/modules/export/**, src/database/migrations/** n'a été modifié (cf. cross_module_protections: []).

3. Couverture des invariants & forbidden (code contract)¶

3.1 Invariants¶

3.2 Forbidden¶

4. Décisions architecturales (decision trace)¶

Format imposé par §"Decision trace pendant l'implémentation" (ajout dans architectural_decisions du code contract module).

architectural_decisions:
  - decision: "Colonne TypeORM `state` typée `varchar(32)` côté entity malgré le type Postgres `export_state_enum`"
    rationale: |
      Le contrat impose un ENUM Postgres (porté par la migration et le trigger). Le mapping
      TypeORM utilise volontairement `varchar` plutôt que `type:'enum'` pour rester cohérent
      avec le pattern PD-103 (capture_events) et éviter le piège `ALTER TYPE ADD VALUE`
      identifié par les REX PD-282/PD-279 si une nouvelle valeur devait être ajoutée.
    alternatives_considered:
      - "type:'enum' + enumName:'export_state_enum' (TypeORM gère les diffs schema)"
      - "VARCHAR + CHECK constraint applicatif (pattern PD-253) — abandonné car le contrat exige ENUM"
    trade_offs: |
      Avantage : ALTER TYPE futur reste possible sans migration synchrone TypeORM.
      Inconvénient : la contrainte de domaine est portée par Postgres, pas par TypeScript ;
      l'entité accepte n'importe quelle string en RAM. Mitigation : `ExportStateMachine` est
      l'unique point d'écriture, et le trigger PG bloque les UPDATE hors matrice.

  - decision: "Worker piloté par `@Interval` plutôt que `@Cron`"
    rationale: |
      Tick 30 s, sub-minute. `@Cron` accepte des expressions sub-minute mais `@Interval`
      est sémantiquement plus juste pour un poll fixe et permet d'utiliser un nom unique
      (`'pd286-expired-export'`) pour l'introspection / l'arrêt sélectif.
    alternatives_considered:
      - "@Cron('*/30 * * * * *')"
      - "Worker dédié hors NestJS (pg-boss) — overkill pour un poll"
    trade_offs: |
      Avantage : simplicité, intégration directe ScheduleModule (déjà importé via app.module).
      Inconvénient : pas de jitter par défaut entre instances. Acceptable car un seul tick
      effectif grâce à `pg_try_advisory_lock` (les autres instances skippent).

5. Vérifications effectuées¶

• npx tsc --noEmit -p tsconfig.json : 0 erreur sur les 8 fichiers livrés (les 2 erreurs résiduelles complaint-file-response.dto.ts et merkle-proof-v2.controller.ts sont hors périmètre — appartiennent respectivement au module C2 export-multi-dto et au module merkle).
• Conventions :
• Branded types (ExportId, ExportSessionUserId) — learning 2026-03-04 (UUID sémantiquement distincts).
• Aucun Math.random() ; tout UUID est généré côté C5 via crypto.randomUUID() (learning 2026-02-21, anti S2245).
• Aucun .catch(() => logger.error(...)) sur appel audit (learning 2026-03-08 anti-catch-absorb).
• Aucun import de canonicalize ou autre lib JCS (réservé à C3/C8).
• Schéma vault_secure cohérent avec PD-103 et autres tables sensibles.

6. Hypothèses d'implémentation (à valider en intégration)¶

7. Observabilité¶

INTERDIT (par learning 2026-03-08) : log de manifest, log de signedUrl, log de integrityHash complet — non concernés par C4 mais documentés pour cohérence.

8. Cohérence avec PD-85¶

PD-286 ajoute une session persistée (export_sessions) là où PD-85 ne traçait que des résultats synchrones (ExportResultState). Aucune route PD-85 n'est touchée par C4 ; le wiring du module conserve la signature ExportModule PD-85, ne casse pas les imports existants (ExportService, ExportManifestBuilder, etc.) et ajoute uniquement ExportSession aux TypeOrmModule.forFeature([...]).

9. Suivi pour les agents downstream¶

• C5 (controller) : doit appeler ExportStateMachine.transition(session, PLANNED_SINGLE | PLANNED_MULTI | FAILED) dans la transaction qui INSERT la session, et émettre l'audit C6 dans la même TX (anti-catch-absorb).
• C6 (audit) : append synchrone dans la même dataSource.transaction() que la transition. Le service ExportStateMachine ne persiste pas, donc C6 reste libre de l'ordre des opérations.
• C7/C8/C9 (app) : la machine app est distincte (cf. plan §1.2 C7) ; aucun couplage runtime avec le service backend, mais la matrice doit rester identique entre les deux pour que les transitions backend ↔ app convergent. Drift à vérifier en intégration / TC-INV-10.
• C11 (tests) : utiliser ExportStateMachine.listAllowedTransitions() (helper statique) pour itérer le produit cartésien dans TC-INV-10 ; le trigger PG doit valider exactement la même matrice (test d'intégration DB réelle).