ephia-protocol

Contrat universel EphiaAudioEvent — le cœur du système.

Rôle et consommateurs autorisés

ephia-protocol est le contrat wire interne d'Ephia : types, schemas Zod, fixtures et changelog protocolaire. Voir docs/wire-contract.md et docs/protocol-versioning.md pour le détail des invariants actuels (protocole v3 : segment.canonical, commandSeq, ephiaWireServerEventSchema).

Il est consommé directement par :

• @ephia/sdk (packages/ephia-sdk) — seul runtime client autorisé à interpréter le wire ;
• les tests de contrat de ce package ;
• le backend Python via les fixtures JSON de src/fixtures/.

Il n'est pas une API cliente. Les apps ne doivent pas importer les schemas wire (ephiaWireServerEventSchema, etc.) pour parser ou appliquer la dictée directement — elles consomment uniquement @ephia/sdk, qui réexporte les types publics nécessaires.

Note : le reste de ce README (sections « Enveloppe commune », « Événements par catégorie », exemple transcript.segment.committed) décrit un modèle d'événements antérieur au protocole v3 actuel et n'a pas été mis à jour dans le cadre de cette PR — à corriger séparément.

Principe fondamental

Protocol > Framework

Ce package est indépendant. Il ne dépend ni du SDK, ni de React, ni de LiveKit, ni du backend.

Il contient :

• types TypeScript des événements publics
• schémas Zod pour validation runtime
• messages client
• états de session
• codes d'erreur
• version du protocole (3 wire / "3.0" REST capabilities)

À quoi sert ce dossier ?

packages/protocol est le contrat partagé du produit audio. Il évite que le backend et le SDK évoluent avec des définitions d'événements divergentes.

Concrètement :

• le backend doit émettre des payloads JSON conformes aux schémas de ce package
• le SDK importe les types pour typer ses reducers, handlers et callbacks
• le SDK valide chaque événement reçu avec ephiaAudioEventSchema.safeParse()
• les tests peuvent vérifier la compatibilité backend/SDK à partir d'une seule source de vérité

Le backend Python n'importe pas le code TypeScript directement. La contrainte est contractuelle : les noms d'événements, champs obligatoires et formats de payload doivent rester compatibles avec les schémas Zod publiés ici.

Enveloppe commune (tous les événements)

{
  "protocolVersion": 3,
  "eventId": "550e8400-e29b-41d4-a716-446655440000",
  "sessionId": "sess_abc",
  "type": "transcript.segment.committed",
  "seq": 42,
  "timestampMs": 1716200000000,
  "payload": { "..." },
  "meta": { "provider": "voxtral-small", "latencyMs": 340 }
}

• seq : strictement croissant par session
• eventId : UUID unique
• timestampMs : timestamp serveur
• sessionId : obligatoire sur tous les events
• meta : optionnel — diagnostics, latences, modes

Règles du protocole

• Aucun preview/stable ne doit écraser un segment déjà committed
• committed insère la version courante du texte de façon atomique
• reviewing signale une review SMART sans changer le texte
• corrected remplace exactement le segment committed correspondant
• review.rejected termine une review sans changement de texte
• Ordre événementiel déterministe par seq

Règle d'atomicité des fusions

transcript.segment.committed est l'événement atomique d'application documentaire.

Lorsqu'un segment absorbe d'autres segments, le payload mergedWith contient les IDs absorbés. Le client doit appliquer le commit final et la suppression des absorbés dans une seule transaction visuelle atomique — jamais en deux étapes séparées.

segment.absorbed est un événement de lifecycle/debug. Il est émis après transcript.segment.committed correspondant. Il ne doit jamais provoquer de suppression visuelle avant le commit fusionné.

Événements par catégorie

Session

Audio / VAD

Pipeline segment (dual)

Transcription — temps réel

Transcription — cycle de vie segment

Document

Flux normal d'un segment

segment.opened
  → transcript.preview         (texte interim, 1..N fois)
  → transcript.preview.stable  (texte stable, 0..N fois)
  → segment.audio.closed       (audio terminé, traitement en cours)
  → transcript.segment.committed  ← appliquer atomiquement
  → [transcript.segment.reviewing
     → transcript.segment.corrected | transcript.segment.review.rejected]

Exemple de payload committed

{
  "protocolVersion": 3,
  "eventId": "550e8400-e29b-41d4-a716-446655440000",
  "sessionId": "sess_abc",
  "type": "transcript.segment.committed",
  "seq": 42,
  "timestampMs": 1716200000000,
  "payload": {
    "segmentId": "seg_12",
    "segmentSeq": 12,
    "text": "Le foie est de taille normale.",
    "source": "voxtral-small",
    "tags": [{ "tag": "anatomy", "word": "foie" }]
  },
  "meta": {
    "provider": "voxtral-small",
    "latencyMs": 820,
    "audioDurationMs": 2300
  }
}

Messages client → backend

Usage

import {
  ephiaAudioEventSchema,
  type EphiaAudioEvent,
  type TranscriptSegmentCommittedEvent,
  PROTOCOL_VERSION,  // 4
} from "ephia-protocol";

// Validation runtime
const parsed = ephiaAudioEventSchema.safeParse(raw);
if (!parsed.success) {
  console.warn("Invalid event:", parsed.error.issues);
  return;
}

// Discrimination par type
const event: EphiaAudioEvent = parsed.data;
if (event.type === "transcript.segment.committed") {
  const { segmentId, text, tags, mergedWith } = event.payload;
  applyToEditor(segmentId, text, { absorbed: mergedWith ?? [] });
}