@ephia/dova-sdk 1.0.0

package/src/core/runtime/TranscriptApplier.test.ts

@@ -0,0 +1,355 @@
+import { describe, expect, it, vi } from "vitest";
+import type { EphiaServerEvent } from "ephia-protocol";
+import type { EphiaBinding } from "../bindings/EphiaBinding";
+import { TranscriptApplier } from "./TranscriptApplier";
+
+function binding(): EphiaBinding {
+  return {
+    kind: "test",
+    attach: vi.fn(),
+    detach: vi.fn(),
+    getText: vi.fn(() => ""),
+    getEditorContext: vi.fn(() => ({
+      targetId: "report",
+      documentEmpty: true,
+      insertionMode: "append" as const,
+      leftContext: "",
+      rightContext: "",
+      selectedText: null,
+      cursorOffset: 0,
+    })),
+    previewSegment: vi.fn(),
+    upsertSegment: vi.fn(),
+    removeSegment: vi.fn(),
+    removeSegments: vi.fn(),
+  };
+}
+
+function operation(
+  overrides: Partial<Extract<EphiaServerEvent, { type: "segment.operation" }>["payload"]> = {},
+  eventId = "evt-op"
+): EphiaServerEvent {
+  return {
+    protocolVersion: 2,
+    type: "segment.operation",
+    eventId,
+    sessionId: "session",
+    serverSeq: 1,
+    sentAt: "2026-06-17T00:00:00+00:00",
+    payload: {
+      segmentId: "seg-1",
+      segmentSeq: 1,
+      segmentRevision: 1,
+      targetId: "report",
+      operation: "upsert",
+      stage: "canonical",
+      text: "texte",
+      textForInsertion: "texte",
+      source: "dova-medical",
+      ...overrides,
+    },
+  };
+}
+
+function targetManager(report?: EphiaBinding, active?: EphiaBinding) {
+  return {
+    get: (id: string) =>
+      id === "report" && report ? { id, binding: report } : undefined,
+    getActiveTarget: () =>
+      active ? { id: "active", binding: active } : undefined,
+    getActiveTargetId: () => (active ? "active" : null),
+  };
+}
+
+describe("TranscriptApplier", () => {
+  it("routes preview to previewSegment on the explicit target", () => {
+    const report = binding();
+    const active = binding();
+    const applier = new TranscriptApplier({ targetManager: targetManager(report, active) });
+
+    applier.handleEvent({
+      protocolVersion: 2,
+      type: "segment.preview",
+      eventId: "evt-preview",
+      sessionId: "session",
+      serverSeq: 1,
+      sentAt: "2026-06-17T00:00:00+00:00",
+      payload: {
+        segmentId: "seg-1",
+        segmentSeq: 1,
+        segmentRevision: 1,
+        targetId: "report",
+        text: "prev",
+      },
+    });
+
+    expect(report.previewSegment).toHaveBeenCalledWith({ id: "seg-1", text: "prev" });
+    expect(active.previewSegment).not.toHaveBeenCalled();
+  });
+
+  it("routes upsert to upsertSegment on the explicit target", () => {
+    const report = binding();
+    const active = binding();
+    const applier = new TranscriptApplier({ targetManager: targetManager(report, active) });
+
+    applier.handleEvent(operation());
+
+    expect(report.upsertSegment).toHaveBeenCalledWith({
+      id: "seg-1",
+      text: "texte",
+      stage: "canonical",
+      source: "dova-medical",
+    });
+    expect(active.upsertSegment).not.toHaveBeenCalled();
+  });
+
+  it("ignores segment.operation without targetId", () => {
+    const active = binding();
+    const warn = vi.fn();
+    const applier = new TranscriptApplier({ targetManager: targetManager(undefined, active), warn });
+
+    applier.handleEvent(operation({ targetId: undefined }));
+
+    expect(active.upsertSegment).not.toHaveBeenCalled();
+    expect(warn).toHaveBeenCalledWith(
+      "[ephia] segment.operation missing targetId; event ignored",
+      expect.objectContaining({ segmentId: "seg-1" })
+    );
+  });
+
+  it("uses textForInsertion over text", () => {
+    const target = binding();
+    const applier = new TranscriptApplier({
+      targetManager: {
+        get: () => ({ id: "report", binding: target }),
+        getActiveTarget: () => undefined,
+        getActiveTargetId: () => null,
+      },
+    });
+
+    applier.handleEvent(operation({ text: "raw", textForInsertion: "formatted" }));
+
+    expect(target.upsertSegment).toHaveBeenCalledWith(
+      expect.objectContaining({ text: "formatted" })
+    );
+  });
+
+  it("absorb: upserts primary then removes absorbed", () => {
+    const target = binding();
+    const applier = new TranscriptApplier({
+      targetManager: {
+        get: () => ({ id: "report", binding: target }),
+        getActiveTarget: () => undefined,
+        getActiveTargetId: () => null,
+      },
+    });
+
+    applier.handleEvent(operation({ operation: "absorb", absorbedSegmentIds: ["seg-0"] }));
+
+    expect(target.upsertSegment).toHaveBeenCalledWith(expect.objectContaining({ id: "seg-1" }));
+    expect(target.removeSegments).toHaveBeenCalledWith(["seg-0"]);
+  });
+
+  it("delete: calls removeSegment and removeSegments for absorbed", () => {
+    const target = binding();
+    const applier = new TranscriptApplier({
+      targetManager: {
+        get: () => ({ id: "report", binding: target }),
+        getActiveTarget: () => undefined,
+        getActiveTargetId: () => null,
+      },
+    });
+
+    applier.handleEvent(
+      operation({ operation: "delete", text: "", textForInsertion: "", absorbedSegmentIds: ["seg-x"] })
+    );
+
+    expect(target.removeSegment).toHaveBeenCalledWith("seg-1");
+    expect(target.removeSegments).toHaveBeenCalledWith(["seg-x"]);
+    expect(target.upsertSegment).not.toHaveBeenCalled();
+  });
+
+  it("noop: does nothing on the binding", () => {
+    const target = binding();
+    const applier = new TranscriptApplier({
+      targetManager: {
+        get: () => ({ id: "report", binding: target }),
+        getActiveTarget: () => undefined,
+        getActiveTargetId: () => null,
+      },
+    });
+
+    applier.handleEvent(operation({ operation: "noop" }));
+
+    expect(target.upsertSegment).not.toHaveBeenCalled();
+    expect(target.removeSegment).not.toHaveBeenCalled();
+  });
+
+  it("warns when target not found", () => {
+    const warn = vi.fn();
+    const applier = new TranscriptApplier({
+      targetManager: {
+        get: () => undefined,
+        getActiveTarget: () => undefined,
+        getActiveTargetId: () => null,
+      },
+      warn,
+    });
+
+    applier.handleEvent(operation());
+
+    expect(warn).toHaveBeenCalledWith(
+      "[ephia] target not found; transcript event ignored",
+      expect.objectContaining({ targetId: "report", segmentId: "seg-1" })
+    );
+  });
+
+  it("ignores duplicate eventId", () => {
+    const target = binding();
+    const applier = new TranscriptApplier({
+      targetManager: {
+        get: () => ({ id: "report", binding: target }),
+        getActiveTarget: () => undefined,
+        getActiveTargetId: () => null,
+      },
+    });
+
+    applier.handleEvent(operation({}, "evt-1"));
+    applier.handleEvent(operation({ segmentRevision: 2 }, "evt-1"));
+
+    expect(target.upsertSegment).toHaveBeenCalledTimes(1);
+  });
+
+  it("ignores stale segmentRevision", () => {
+    const target = binding();
+    const applier = new TranscriptApplier({
+      targetManager: {
+        get: () => ({ id: "report", binding: target }),
+        getActiveTarget: () => undefined,
+        getActiveTargetId: () => null,
+      },
+    });
+
+    applier.handleEvent(operation({ segmentRevision: 2 }, "evt-2"));
+    applier.handleEvent(operation({ segmentRevision: 1 }, "evt-3"));
+
+    expect(target.upsertSegment).toHaveBeenCalledTimes(1);
+  });
+
+  it("applies higher segmentRevision", () => {
+    const target = binding();
+    const applier = new TranscriptApplier({
+      targetManager: {
+        get: () => ({ id: "report", binding: target }),
+        getActiveTarget: () => undefined,
+        getActiveTargetId: () => null,
+      },
+    });
+
+    applier.handleEvent(operation({ segmentRevision: 1, text: "un", textForInsertion: "un" }, "evt-4"));
+    applier.handleEvent(operation({ segmentRevision: 2, text: "deux", textForInsertion: "deux" }, "evt-5"));
+
+    expect(target.upsertSegment).toHaveBeenCalledTimes(2);
+    expect(target.upsertSegment).toHaveBeenLastCalledWith(
+      expect.objectContaining({ id: "seg-1", text: "deux" })
+    );
+  });
+
+  it("does not mark event seen when target is absent", () => {
+    let callCount = 0;
+    const applier = new TranscriptApplier({
+      targetManager: {
+        get: () => {
+          callCount++;
+          return callCount >= 2 ? { id: "report", binding: binding() } : undefined;
+        },
+        getActiveTarget: () => undefined,
+        getActiveTargetId: () => null,
+      },
+      warn: () => {},
+    });
+
+    // First call — target absent → event NOT marked as seen.
+    applier.handleEvent(operation({}, "evt-retry"));
+    // Second call same eventId — target now present → should be applied.
+    applier.handleEvent(operation({}, "evt-retry"));
+
+    // The second call should reach upsertSegment (event was not marked as seen on first pass).
+    // We can't directly assert on the binding from the outer scope, but the test verifies
+    // no error is thrown and we can instrument via the targetManager.
+    expect(callCount).toBeGreaterThanOrEqual(2);
+  });
+
+  it("ignores late preview after canonical applied", () => {
+    const target = binding();
+    const applier = new TranscriptApplier({
+      targetManager: {
+        get: () => ({ id: "report", binding: target }),
+        getActiveTarget: () => undefined,
+        getActiveTargetId: () => null,
+      },
+    });
+
+    // Apply canonical first.
+    applier.handleEvent(operation({ stage: "canonical", segmentRevision: 2 }, "evt-canonical"));
+
+    // Late preview for same segment should be ignored.
+    applier.handleEvent({
+      protocolVersion: 2,
+      type: "segment.preview",
+      eventId: "evt-late-preview",
+      sessionId: "session",
+      serverSeq: 3,
+      sentAt: "2026-06-17T00:00:00+00:00",
+      payload: {
+        segmentId: "seg-1",
+        segmentSeq: 1,
+        segmentRevision: 1,
+        targetId: "report",
+        text: "stale preview",
+      },
+    });
+
+    expect(target.previewSegment).not.toHaveBeenCalled();
+    expect(target.upsertSegment).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not mark preview seen if target absent (allows replay)", () => {
+    let targetAvailable = false;
+    const targetBinding = binding();
+    const applier = new TranscriptApplier({
+      targetManager: {
+        get: () =>
+          targetAvailable ? { id: "report", binding: targetBinding } : undefined,
+        getActiveTarget: () => undefined,
+        getActiveTargetId: () => null,
+      },
+      warn: () => {},
+    });
+
+    const previewEvent: EphiaServerEvent = {
+      protocolVersion: 2,
+      type: "segment.preview",
+      eventId: "evt-preview-retry",
+      sessionId: "session",
+      serverSeq: 1,
+      sentAt: "2026-06-17T00:00:00+00:00",
+      payload: {
+        segmentId: "seg-1",
+        segmentSeq: 1,
+        segmentRevision: 1,
+        targetId: "report",
+        text: "partial",
+      },
+    };
+
+    // Target absent — preview not applied, not marked as seen.
+    applier.handleEvent(previewEvent);
+    expect(targetBinding.previewSegment).not.toHaveBeenCalled();
+
+    // Target now available — same event replayed.
+    targetAvailable = true;
+    applier.handleEvent(previewEvent);
+    expect(targetBinding.previewSegment).toHaveBeenCalledWith({ id: "seg-1", text: "partial" });
+  });
+});

package/src/core/runtime/TranscriptApplier.ts

@@ -0,0 +1,229 @@
+import type { EphiaServerEvent, SegmentOperationPayload } from "ephia-protocol";
+import type { EphiaBinding } from "../bindings/EphiaBinding";
+import type { TargetManager } from "../targets/TargetManager";
+
+export type TranscriptApplierOptions = {
+  targetManager: Pick<TargetManager, "get" | "getActiveTarget" | "getActiveTargetId">;
+  warn?: (message: string, details?: Record<string, unknown>) => void;
+  debug?: (message: string, details?: Record<string, unknown>) => void;
+};
+
+const MAX_SEEN_EVENTS = 1000;
+const MAX_PENDING_EVENTS = 50;
+
+/**
+ * Applique les events serveur V2 aux bindings éditeurs enregistrés.
+ *
+ * Règles de stricte V2 :
+ *  - targetId obligatoire sur segment.operation
+ *  - eventId déjà vu → ignore
+ *  - segmentRevision inférieure ou égale à la dernière appliquée → ignore
+ *  - upsert/absorb atomique (upsert puis remove absorbed)
+ *  - segment.preview ignoré si un canonical a déjà été appliqué pour ce segment
+ *  - event/revision non marqués comme vus si le binding n'est pas encore disponible
+ */
+export class TranscriptApplier {
+  private readonly targetManager: TranscriptApplierOptions["targetManager"];
+  private readonly warn: NonNullable<TranscriptApplierOptions["warn"]>;
+  private readonly debug: NonNullable<TranscriptApplierOptions["debug"]>;
+
+  /** eventId → déjà traité (idempotence). */
+  private readonly seenEventIds = new Set<string>();
+  private readonly seenEventQueue: string[] = [];
+
+  /** segmentId → dernière segmentRevision appliquée. */
+  private readonly latestRevisionBySegment = new Map<string, number>();
+
+  /** segmentId → targetId (cache défensif). */
+  private readonly segmentTargetMap = new Map<string, string>();
+
+  /** segmentIds pour lesquels un canonical a été appliqué avec succès. */
+  private readonly canonicalSegments = new Set<string>();
+
+  /** Events en attente de montage de leur cible (targetId → events[]). */
+  private readonly pendingEvents = new Map<string, EphiaServerEvent[]>();
+
+  constructor(options: TranscriptApplierOptions) {
+    this.targetManager = options.targetManager;
+    this.warn = options.warn ?? ((message, details) => console.warn(message, details));
+    this.debug = options.debug ?? (() => {});
+  }
+
+  handleEvent(event: EphiaServerEvent): void {
+    // Check for duplicate WITHOUT marking yet — we only mark after successful application.
+    if (this.seenEventIds.has(event.eventId)) {
+      this.debug("duplicate event ignored", { eventId: event.eventId, type: event.type });
+      return;
+    }
+
+    if (event.type === "segment.preview") {
+      // Ignore previews that arrive after a canonical was already applied.
+      if (this.canonicalSegments.has(event.payload.segmentId)) {
+        this.debug("late preview ignored after canonical", {
+          segmentId: event.payload.segmentId,
+        });
+        this._markEventSeen(event.eventId);
+        return;
+      }
+
+      const binding = this.resolveBinding(event.payload.targetId, event.payload.segmentId);
+      // If binding not found, enqueue event for later replay.
+      if (!binding) {
+        this._enqueuePendingEvent(event, event.payload.targetId);
+        return;
+      }
+
+      this._markEventSeen(event.eventId);
+      binding.previewSegment?.({ id: event.payload.segmentId, text: event.payload.text });
+      return;
+    }
+
+    if (event.type === "segment.operation") {
+      const applied = this.applyOperation(event.payload, event);
+      // Only mark as seen if the event was processed (binding found).
+      // If binding missing, event is enqueued for retry.
+      if (applied) this._markEventSeen(event.eventId);
+    }
+  }
+
+  /**
+   * Rejoue les events en attente pour une cible donnée.
+   * À appeler après l'enregistrement d'une nouvelle target.
+   */
+  flushPendingEvents(targetId: string): void {
+    const pending = this.pendingEvents.get(targetId);
+    if (!pending || pending.length === 0) return;
+
+    this.debug("flushing pending events", { targetId, count: pending.length });
+
+    const toRetry = [...pending];
+    this.pendingEvents.delete(targetId);
+
+    for (const event of toRetry) {
+      this.handleEvent(event);
+    }
+  }
+
+  private applyOperation(payload: SegmentOperationPayload, event?: EphiaServerEvent): boolean {
+    // Resolve binding FIRST — before marking the revision. If binding is absent,
+    // return false so the event stays unmarked and can be enqueued for retry.
+    const binding = this.resolveBinding(payload.targetId, payload.segmentId);
+    if (!binding) {
+      if (event && payload.targetId) {
+        this._enqueuePendingEvent(event, payload.targetId);
+      }
+      return false;
+    }
+
+    if (!this.shouldApplySegmentRevision(payload)) {
+      // Revision already surpassed — event is stale but binding exists; mark as seen.
+      return true;
+    }
+
+    if (payload.operation === "noop") return true;
+
+    if (payload.operation === "delete") {
+      binding.removeSegment(payload.segmentId);
+      if (payload.absorbedSegmentIds?.length) {
+        binding.removeSegments(payload.absorbedSegmentIds);
+      }
+      return true;
+    }
+
+    // "upsert" and "absorb" both upsert the primary segment then remove absorbed.
+    binding.upsertSegment({
+      id: payload.segmentId,
+      text: payload.textForInsertion || payload.text,
+      stage: payload.stage,
+      source: payload.source,
+    });
+
+    if (payload.stage === "canonical") {
+      this.canonicalSegments.add(payload.segmentId);
+    }
+
+    if (payload.absorbedSegmentIds?.length) {
+      binding.removeSegments(payload.absorbedSegmentIds);
+    }
+
+    return true;
+  }
+
+  private shouldApplySegmentRevision(payload: SegmentOperationPayload): boolean {
+    const previous = this.latestRevisionBySegment.get(payload.segmentId);
+    const current = payload.segmentRevision;
+
+    if (previous !== undefined && current <= previous) {
+      this.debug("stale segment revision ignored", {
+        segmentId: payload.segmentId,
+        previous,
+        current,
+      });
+      return false;
+    }
+
+    this.latestRevisionBySegment.set(payload.segmentId, current);
+    return true;
+  }
+
+  private resolveBinding(targetId: string | undefined, segmentId: string): EphiaBinding | null {
+    if (targetId) {
+      const target = this.targetManager.get(targetId);
+      const binding = this.asEphiaBinding(target?.binding);
+      if (!binding) {
+        this.warn("[ephia] target not found; transcript event ignored", {
+          targetId,
+          segmentId,
+        });
+        return null;
+      }
+      this.segmentTargetMap.set(segmentId, targetId);
+      return binding;
+    }
+
+    const mappedTargetId = this.segmentTargetMap.get(segmentId);
+    if (mappedTargetId) {
+      return this.asEphiaBinding(this.targetManager.get(mappedTargetId)?.binding);
+    }
+
+    this.warn("[ephia] segment.operation missing targetId; event ignored", {
+      segmentId,
+    });
+    return null;
+  }
+
+  private _markEventSeen(eventId: string): void {
+    this.seenEventIds.add(eventId);
+    this.seenEventQueue.push(eventId);
+    if (this.seenEventQueue.length > MAX_SEEN_EVENTS) {
+      const oldest = this.seenEventQueue.shift();
+      if (oldest) this.seenEventIds.delete(oldest);
+    }
+  }
+
+  private asEphiaBinding(binding: unknown): EphiaBinding | null {
+    if (!binding) return null;
+    if (typeof binding === "object" && "upsertSegment" in binding) return binding as EphiaBinding;
+    return null;
+  }
+
+  private _enqueuePendingEvent(event: EphiaServerEvent, targetId?: string): void {
+    if (!targetId) return;
+
+    const queue = this.pendingEvents.get(targetId) ?? [];
+    if (queue.length >= MAX_PENDING_EVENTS) {
+      this.debug("pending events queue full, dropping oldest", { targetId });
+      queue.shift();
+    }
+
+    queue.push(event);
+    this.pendingEvents.set(targetId, queue);
+
+    this.debug("event enqueued for target", {
+      targetId,
+      eventId: event.eventId,
+      type: event.type,
+      queueSize: queue.length,
+    });
+  }
+}

package/src/core/runtime/index.ts

@@ -0,0 +1,18 @@
+export {
+  DictationRuntime,
+} from "./DictationRuntime";
+export {
+  TranscriptApplier,
+} from "./TranscriptApplier";
+
+export type {
+  DictationPartialState,
+  DictationRuntimeOptions,
+  DictationRuntimeStatus,
+  DictationTarget,
+  DictationTargetInsertionMode,
+  DictationTargetRegistry,
+} from "./DictationRuntime";
+export type {
+  TranscriptApplierOptions,
+} from "./TranscriptApplier";

package/src/core/session/index.ts

@@ -0,0 +1,2 @@
+export { canTransition, transitionSessionStatus } from "./session-machine";
+export type { EphiaSessionStatus } from "./session-machine";

package/src/core/session/session-machine.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, it } from "vitest";
+import { canTransition, transitionSessionStatus } from "./session-machine";
+
+describe("session-machine", () => {
+  it("allows connecting_transport -> ready -> recording", () => {
+    expect(transitionSessionStatus("connecting_transport", "ready")).toBe("ready");
+    expect(transitionSessionStatus("ready", "recording")).toBe("recording");
+  });
+
+  it("rejects connecting_transport -> recording", () => {
+    expect(canTransition("connecting_transport", "recording")).toBe(false);
+    expect(() => transitionSessionStatus("connecting_transport", "recording")).toThrow(
+      /Transition interdite/
+    );
+  });
+});

package/src/core/session/session-machine.ts

@@ -0,0 +1,59 @@
+/**
+ * Machine à états stricte pour les sessions Ephia Audio.
+ *
+ * Interdit les transitions invalides (ex: recording -> creating_session).
+ */
+
+import { EphiaSdkError } from "../../shared/errors/EphiaSdkError";
+
+export type EphiaSessionStatus =
+  | "idle"
+  | "creating_session"
+  | "connecting_transport"
+  | "ready"
+  | "recording"
+  | "paused"
+  | "finalizing"
+  | "ended"
+  | "error"
+  | "disposed";
+
+const ALLOWED_TRANSITIONS: Record<EphiaSessionStatus, EphiaSessionStatus[]> = {
+  idle: ["creating_session", "disposed"],
+  creating_session: ["connecting_transport", "error", "disposed"],
+  connecting_transport: ["ready", "error", "disposed"],
+  ready: ["recording", "finalizing", "error", "disposed"],
+  recording: ["paused", "finalizing", "error", "disposed"],
+  paused: ["recording", "finalizing", "error", "disposed"],
+  // "paused" : stop() passe par finalizing pendant le drain backend, puis retombe en paused
+  finalizing: ["paused", "ended", "error", "disposed"],
+  ended: ["idle", "disposed"],
+  error: ["idle", "disposed"],
+  disposed: [],
+};
+
+export function transitionSessionStatus(
+  current: EphiaSessionStatus,
+  next: EphiaSessionStatus
+): EphiaSessionStatus {
+  if (current === next) return current;
+
+  const allowed = ALLOWED_TRANSITIONS[current] ?? [];
+  if (!allowed.includes(next)) {
+    throw new EphiaSdkError(
+      "client.invalid_state",
+      `Transition interdite: ${current} -> ${next}`,
+      { current, next, allowed }
+    );
+  }
+  return next;
+}
+
+export function canTransition(
+  current: EphiaSessionStatus,
+  next: EphiaSessionStatus
+): boolean {
+  if (current === next) return true;
+  const allowed = ALLOWED_TRANSITIONS[current] ?? [];
+  return allowed.includes(next);
+}