PD-103 — Agent Developer — Module M1 : capture-state-machine¶

1. Identite agent¶

• Agent : agent-developer (Agent B — Claude)
• Story : PD-103
• Module : M1 — capture-state-machine
• Wave : 1 (fondation, sans dependance inter-agents)
• Date : 2026-04-03

2. Resume¶

Module M1 implemente la machine d'etats monotone a 8 etats pour la capture probatoire d'ecran. Le module fournit la validation structurelle des transitions, les gardes metier contractuelles, le terminal enforcement et la journalisation des transitions.

Fichiers crees : - src/capture/state-machine.ts — Implementation FSM - src/__tests__/capture/state-machine.test.ts — 90 tests (contractuels + non-regression)

Fichier existant reutilise : - src/capture/types.ts — Types, etats, constantes, table de transitions (T1 capture-types)

3. Artefacts livres¶

4. Architecture¶

4.1 Pattern utilise¶

Pattern identique a src/seal/state-machine.ts (PD-284) : - Table ALLOWED_TRANSITIONS exhaustive (importee de types.ts) - Fonction pure canTransition(from, to) sans effet de bord - Fonction pure isTerminalCaptureState(state) - Classe CaptureStateMachine avec etat mutable + log immutable - Erreur typee InvalidCaptureTransitionError avec from, to, code

4.2 Enrichissements par rapport au pattern existant¶

4.3 Gardes de transition implementees¶

4.4 Exports publics¶

// Classes
export class CaptureStateMachine { ... }
export class InvalidCaptureTransitionError extends Error { ... }

// Interface
export interface TransitionGuardContext { ... }

// Fonctions pures
export function canTransition(from, to): boolean
export function isTerminalCaptureState(state): boolean
export function evaluateGuard(from, to, ctx): string | null

4.5 Diagramme¶

stateDiagram-v2
    [*] --> CAPTURED

    CAPTURED --> UPLOADING : hash+encrypt OK
    CAPTURED --> CANCELLED : user cancel

    UPLOADING --> UPLOADED : S3+ACK OK
    UPLOADING --> UPLOAD_DEFERRED : reseau KO
    UPLOADING --> CANCELLED : user cancel

    UPLOAD_DEFERRED --> UPLOADING : JWT+URL OK
    UPLOAD_DEFERRED --> CANCELLED : TTL expire

    UPLOADED --> PENDING_SEAL
    PENDING_SEAL --> SEALED : SIGNED+hsm_ref
    SEALED --> ANCHOR_CONFIRMED : blockchain OK

    ANCHOR_CONFIRMED --> [*]
    CANCELLED --> [*]

5. Couverture de tests¶

5.1 Metriques¶

5.2 Matrice de couverture TC-* -> fichiers de test¶

5.3 Tests additionnels (NON-CONTRACTUAL)¶

6. Decisions architecturales¶

6.1 Gardes comme fonction pure separee¶

• Decision : evaluateGuard() est une fonction pure exportee, separee de la classe FSM.
• Rationale : Permet de tester les gardes isolement sans instancier la machine. Les consumers (M6 orchestrator) peuvent pre-valider une transition sans effet de bord.
• Alternatives considerees : Gardes inline dans transition() (moins testable), gardes comme methodes privees (non exportable).
• Trade-offs : Legere duplication du mapping (from, to) dans evaluateGuard par rapport a la table ALLOWED_TRANSITIONS, mais meilleure lisibilite et testabilite.

6.2 Timestamp ISO 8601 au lieu de Date.now()¶

• Decision : Les entrees du log utilisent new Date().toISOString() (ISO 8601 UTC) au lieu de Date.now() (millisecondes epoch).
• Rationale : Alignement avec le format contractuel timestamp_device (RFC3339 UTC) et l'interface CaptureTransitionLog de types.ts. Facilite la correlation avec les logs backend.
• Alternatives considerees : Date.now() (pattern PD-284), performance.now() (PD-284 learning).
• Trade-offs : Microseconde de surcharge pour la serialisation ISO ; acceptable car les transitions sont evenementielles et non critiques en latence.

7. Hypotheses¶

8. Dependances¶

9. Invariants couverts¶

10. Limites connues¶

1. Pas de resync serveur : Contrairement a SealStateMachine (PD-284), pas de methode resync(). Le besoin n'est pas identifie dans la spec PD-103 pour le mobile. Si necessaire, a ajouter dans une iteration ulterieure.

2. Gardes evaluees localement : La garde PENDING_SEAL -> SEALED (INV-103-08) est implementee mais sera probablement evaluee cote backend. Cote mobile, la transition sera declenchee par SSE/polling sans re-evaluation locale de la garde.

3. Pas de persistence : La machine d'etats est en memoire. La persistence est deleguee a M5 (useCaptureStore) qui reconstituera l'etat au redemarrage.

11. Checklist qualite¶

• 0 erreur TypeScript (strict: true)
• Coverage > 80% (lignes, branches, fonctions)
• Tous les tests TC-* contractuels implementes
• Tests NON-CONTRACTUAL identifies comme tels
• Aucune modification de fichier hors perimetre
• Aucune deviation par rapport a la specification
• Aucune fonctionnalite non prevue ajoutee
• Pattern existant (PD-284) respecte et enrichi