@poolse/react-native-calls 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,34 @@
-# Temporary Holding Version
+# @poolse/react-native-calls
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The React Native bridge over poolse's native call core — the Kotlin
+(`dev.poolse:call-core`) and, later, Swift engines that ring, answer and
+carry audio with the app killed and the phone locked.
+
+This package is thin on purpose: commands go in, one `Snapshot` event
+comes out, and every call decision lives in the native core (behaviour
+pinned by `contracts/call-core/vectors.json`). On a build without the
+native module it degrades to safe no-ops with an idle state, so a host
+can render against it unconditionally.
+
+```ts
+import * as calls from '@poolse/react-native-calls';
+
+await calls.configure('https://api.poolse.dev', { smallIcon: 'ic_call', ringback: 'ringback' });
+const stop = calls.onCallState((s) => render(s));   // s: Snapshot | null
+await calls.place(conversationId, { media: 'audio', sessionToken });
+calls.answer(); calls.decline(); calls.hangUp();
+```
+
+## Layout
+- `src/` — the TypeScript API (this is what apps import).
+- `android/src/main/java/dev/poolse/callcore/` — the pure state machine
+  and ports (contract cv 1).
+- `android/src/main/java/dev/poolse/callcore/android/` — the Android
+  adapters (HTTP, timers, ring surface, foreground service, FCM intake,
+  composition root).
+- `android/src/main/java/expo/modules/poolsecalls/` — the Expo bridge
+  module (compiled by the app's autolinking).
+- `android/src/main/livekit/` — the shipped LiveKit `MediaPort`, opt-in
+  via the `poolse.livekit` gradle property; the core is SFU-agnostic.
+
+Stage 3 adds the Swift core under `ios/`.

package/android/build.gradle

@@ -0,0 +1,51 @@
+apply plugin: 'com.android.library'
+apply plugin: 'kotlin-android'
+
+group = 'dev.poolse.callcore'
+version = '0.1.0'
+
+def expoModulesCorePlugin = new File(project(":expo-modules-core").projectDir.absolutePath, "ExpoModulesCorePlugin.gradle")
+apply from: expoModulesCorePlugin
+applyKotlinExpoModulesCorePlugin()
+useCoreDependencies()
+
+def safeExtGet(prop, fallback) {
+  rootProject.ext.has(prop) ? rootProject.ext.get(prop) : fallback
+}
+
+// The shipped LiveKit MediaPort lives in its own source set, off the
+// core classpath, so the library carries no SFU dependency unless the
+// app opts in with `-Ppoolse.livekit` (or ext.poolseLiveKit = true).
+def useLiveKit = project.hasProperty('poolse.livekit') ||
+  (rootProject.ext.has('poolseLiveKit') && rootProject.ext.get('poolseLiveKit'))
+
+android {
+  namespace "dev.poolse.callcore"
+  compileSdk safeExtGet("compileSdkVersion", 36)
+
+  defaultConfig {
+    minSdkVersion safeExtGet("minSdkVersion", 24)
+    targetSdkVersion safeExtGet("targetSdkVersion", 36)
+    versionCode 1
+    versionName "0.1.0"
+  }
+
+  if (useLiveKit) {
+    sourceSets {
+      main {
+        java.srcDir "src/main/livekit/java"
+      }
+    }
+  }
+}
+
+dependencies {
+  implementation 'androidx.core:core-ktx:1.13.1'
+  implementation 'com.squareup.okhttp3:okhttp:4.12.0'
+  implementation 'com.google.firebase:firebase-messaging:24.0.3'
+  implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:1.8.1'
+
+  if (useLiveKit) {
+    implementation 'io.livekit:livekit-android:2.11.0'
+  }
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,40 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+  <uses-permission android:name="android.permission.INTERNET" />
+  <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+  <uses-permission android:name="android.permission.USE_FULL_SCREEN_INTENT" />
+  <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
+  <uses-permission android:name="android.permission.FOREGROUND_SERVICE_PHONE_CALL" />
+  <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MICROPHONE" />
+  <uses-permission android:name="android.permission.RECORD_AUDIO" />
+  <uses-permission android:name="android.permission.VIBRATE" />
+  <uses-permission android:name="android.permission.WAKE_LOCK" />
+
+  <application>
+    <activity
+      android:name="dev.poolse.callcore.android.IncomingCallActivity"
+      android:exported="false"
+      android:showWhenLocked="true"
+      android:turnScreenOn="true"
+      android:excludeFromRecents="true"
+      android:launchMode="singleInstance"
+      android:theme="@android:style/Theme.Black.NoTitleBar.Fullscreen" />
+
+    <receiver
+      android:name="dev.poolse.callcore.android.CallActionReceiver"
+      android:exported="false" />
+
+    <service
+      android:name="dev.poolse.callcore.android.CallForegroundService"
+      android:exported="false"
+      android:foregroundServiceType="phoneCall|microphone" />
+
+    <service
+      android:name="dev.poolse.callcore.android.CallMessagingService"
+      android:exported="false">
+      <intent-filter>
+        <action android:name="com.google.firebase.MESSAGING_EVENT" />
+      </intent-filter>
+    </service>
+  </application>
+</manifest>

package/android/src/main/java/dev/poolse/callcore/CallCoreRuntime.kt

@@ -0,0 +1,257 @@
+package dev.poolse.callcore
+
+/**
+ * The engine around the machine: owns the state, serializes events,
+ * executes effects through the ports, runs the timers, and emits a
+ * snapshot after every change.
+ *
+ * The machine decides; this class merely obeys — there is deliberately
+ * no call logic here beyond bookkeeping the effects need (which grant
+ * answers which call, which control token hangs up). If behavior is
+ * wrong, the fix is in CallMachine + vectors, not here.
+ *
+ * Thread-safe: adapters may call in from any thread; dispatch is
+ * serialized on an internal lock. The Android bridge hops results back
+ * to its own looper via TimerPort's scheduling.
+ */
+class CallCoreRuntime(
+  private val http: HttpPort,
+  private val media: MediaPort,
+  private val surface: RingSurfacePort,
+  private val session: CallSessionPort,
+  private val timers: TimerPort,
+  private val sink: SnapshotSink,
+) {
+  private val lock = Any()
+
+  private var state: MachineState = MachineState.IDLE
+
+  /** The ring being shown (its grant answers/declines it). */
+  private var ring: RingContext? = null
+
+  /** Grants of rings auto-declined busy, kept until the decline fires. */
+  private val busyRings = mutableMapOf<String, RingContext>()
+
+  /** The session bundle of the current call, once the server accepted. */
+  private var bundle: CallSessionBundle? = null
+
+  /** The session token place/join were called with, for one retry. */
+  private var sessionToken: String? = null
+
+  private companion object {
+    const val ENDED_LINGER_MS = 2_500L
+    const val RECONNECT_BUDGET_MS = 25_000L
+    const val T_DEADLINE = "ring_deadline"
+    const val T_LINGER = "linger"
+    const val T_RECONNECT = "reconnect_budget"
+  }
+
+  // ── inputs from adapters ────────────────────────────────────────────
+
+  fun currentState(): MachineState = synchronized(lock) { state }
+
+  /** A ring arrived — push or socket, the machine treats them alike. */
+  fun onRing(ctx: RingContext) {
+    val stale = ctx.ringDeadlineEpochMs <= timers.nowMs()
+    synchronized(lock) {
+      // Remember the context BEFORE dispatch: the effects need it —
+      // SHOW_RING for this call, or HTTP_DECLINE_BUSY for another.
+      if (!stale) busyRings[ctx.callId] = ctx
+      dispatch(
+        Event.Ring(
+          callId = ctx.callId,
+          conversationId = ctx.conversationId,
+          media = ctx.media,
+          stale = stale,
+        ),
+        ringCtx = ctx,
+      )
+      busyRings.remove(ctx.callId)
+    }
+  }
+
+  fun onRingEnded(callId: String, reason: String) =
+    synchronized(lock) { dispatch(Event.RingEnded(callId, reason)) }
+
+  fun onCallFinished(callId: String) =
+    synchronized(lock) { dispatch(Event.CallFinished(callId)) }
+
+  fun answer() = synchronized(lock) { dispatch(Event.UserAnswer) }
+  fun decline() = synchronized(lock) { dispatch(Event.UserDecline) }
+  fun hangUp() = synchronized(lock) { dispatch(Event.UserHangup) }
+
+  fun place(conversationId: String, media: String, sessionToken: String) =
+    synchronized(lock) {
+      this.sessionToken = sessionToken
+      // call_id is server-minted on place; a placeholder keys the state
+      // until the bundle arrives.
+      dispatch(Event.UserPlace(callId = "pending:$conversationId", conversationId = conversationId, media = media))
+    }
+
+  fun join(callId: String, conversationId: String?, sessionToken: String) =
+    synchronized(lock) {
+      this.sessionToken = sessionToken
+      dispatch(Event.UserJoin(callId, conversationId))
+    }
+
+  /** Caller-side: the bridge resolved every ring from `ring_states`. */
+  fun allRingsResolved(outcome: String) =
+    synchronized(lock) { dispatch(Event.AllRingsResolved(outcome)) }
+
+  fun onMediaConnected() = synchronized(lock) { dispatch(Event.MediaConnected) }
+  fun onMediaFailed() = synchronized(lock) { dispatch(Event.MediaFailed) }
+  fun onMediaLost() = synchronized(lock) { dispatch(Event.MediaLost) }
+  fun onMediaRecovered() = synchronized(lock) { dispatch(Event.MediaRecovered) }
+  fun onRemoteJoined() = synchronized(lock) { dispatch(Event.RemoteJoined) }
+
+  fun setMuted(muted: Boolean) = media.setMuted(muted)
+  fun setCamera(on: Boolean) = media.setCamera(on)
+  fun switchCamera() = media.switchCamera()
+
+  // ── dispatch ────────────────────────────────────────────────────────
+
+  private fun dispatch(event: Event, ringCtx: RingContext? = null) {
+    val before = state
+    val (next, effects) = CallMachine.transition(before, event)
+    state = next
+    for (effect in effects) execute(effect, ringCtx)
+    // Retire the ring grant only after EVERY effect has had its chance
+    // to use it. CONNECTING keeps it (answer + the no-bundle hangup
+    // fallback still need it); CallSessionStop clears it with the rest.
+    if (next.phase == Phase.IDLE || next.phase == Phase.ENDED) ring = null
+    runTimers(before, next)
+    if (next != before || effects.isNotEmpty()) sink.emit(next)
+  }
+
+  private fun execute(effect: Effect, ringCtx: RingContext?) {
+    when (effect) {
+      Effect.ShowRing -> {
+        ring = ringCtx
+        ringCtx?.let(surface::show)
+      }
+      Effect.DismissRing -> {
+        (ring ?: ringCtx)?.let { surface.dismiss(it.callId) }
+        // The grant is NOT retired here: HTTP_DECLINE may still be
+        // later in this very effect list (dismiss-then-decline), and
+        // clearing mid-list silently dropped the decline — the exact
+        // "rejection never reached the caller" bug, reborn. Retirement
+        // happens once, after the whole list, in dispatch().
+      }
+      Effect.RingtoneStart -> surface.ringtoneStart()
+      Effect.RingtoneStop -> surface.ringtoneStop()
+      Effect.RingbackStart -> surface.ringbackStart()
+      Effect.RingbackStop -> surface.ringbackStop()
+
+      Effect.HttpAnswer -> {
+        val r = ring
+        if (r != null) http.answer(r.callId, r.grant, ::onHttpResult)
+        else onHttpResult(HttpResult.AuthFailed("no_grant"))
+      }
+      Effect.HttpJoin -> {
+        val callId = state.callId
+        val token = sessionToken
+        if (callId != null && token != null) http.join(callId, token, ::onHttpResult)
+        else onHttpResult(HttpResult.AuthFailed("no_session"))
+      }
+      Effect.HttpPlace -> {
+        val conversationId = state.conversationId
+        val token = sessionToken
+        if (conversationId != null && token != null) {
+          http.place(conversationId, state.media, token, ::onHttpResult)
+        } else onHttpResult(HttpResult.AuthFailed("no_session"))
+      }
+      Effect.HttpDecline -> {
+        ring?.let { http.decline(it.callId, it.grant, busy = false) }
+      }
+      is Effect.HttpDeclineBusy -> {
+        busyRings[effect.callId]?.let { http.decline(it.callId, it.grant, busy = true) }
+      }
+      Effect.HttpHangup -> {
+        val b = bundle
+        val r = ring
+        when {
+          b != null -> http.hangup(b.callId, b.controlToken)
+          // Hanging up a connecting answer that has no bundle yet:
+          // resolve the ring instead, so the caller is not left waiting.
+          r != null -> http.decline(r.callId, r.grant, busy = false)
+          else -> Unit
+        }
+      }
+      Effect.HttpReconnect -> {
+        val b = bundle
+        if (b != null) http.reconnect(b.callId, b.controlToken, ::onReconnectResult)
+        else synchronized(lock) { dispatch(Event.HttpGone) }
+      }
+
+      Effect.MediaJoin -> bundle?.let(media::join)
+      Effect.MediaLeave -> media.leave()
+
+      Effect.CallSessionStart -> session.start(state.callId ?: "", state.media)
+      Effect.CallSessionStop -> {
+        session.stop()
+        bundle = null
+        ring = null
+        sessionToken = null
+      }
+    }
+  }
+
+  private fun onHttpResult(result: HttpResult) {
+    synchronized(lock) {
+      when (result) {
+        is HttpResult.Ok -> {
+          bundle = result.bundle
+          // The server minted the real call id on place.
+          if (state.callId?.startsWith("pending:") == true) {
+            state = state.copy(callId = result.bundle.callId, conversationId = result.bundle.conversationId)
+          }
+          dispatch(Event.HttpOk(created = result.bundle.created))
+        }
+        HttpResult.Gone -> dispatch(Event.HttpGone)
+        HttpResult.Timeout -> dispatch(Event.HttpTimeout)
+        is HttpResult.AuthFailed -> dispatch(Event.HttpGone)
+      }
+    }
+  }
+
+  private fun onReconnectResult(result: HttpResult) {
+    synchronized(lock) {
+      when (result) {
+        is HttpResult.Ok -> {
+          bundle = result.bundle
+          media.join(result.bundle)
+        }
+        HttpResult.Gone, is HttpResult.AuthFailed -> dispatch(Event.HttpGone)
+        HttpResult.Timeout -> Unit // budget timer is the backstop
+      }
+    }
+  }
+
+  // ── timers ──────────────────────────────────────────────────────────
+
+  private fun runTimers(before: MachineState, after: MachineState) {
+    if (before.phase != after.phase) {
+      when (after.phase) {
+        Phase.RINGING_IN -> {
+          val deadline = ring?.ringDeadlineEpochMs ?: return
+          timers.schedule(T_DEADLINE, (deadline - timers.nowMs()).coerceAtLeast(0)) {
+            synchronized(lock) { dispatch(Event.RingDeadline) }
+          }
+        }
+        Phase.ENDED -> timers.schedule(T_LINGER, ENDED_LINGER_MS) {
+          synchronized(lock) { dispatch(Event.LingerElapsed) }
+        }
+        Phase.RECONNECTING -> timers.schedule(T_RECONNECT, RECONNECT_BUDGET_MS) {
+          synchronized(lock) { dispatch(Event.ReconnectBudgetElapsed) }
+        }
+        else -> Unit
+      }
+      when (before.phase) {
+        Phase.RINGING_IN -> timers.cancel(T_DEADLINE)
+        Phase.ENDED -> timers.cancel(T_LINGER)
+        Phase.RECONNECTING -> timers.cancel(T_RECONNECT)
+        else -> Unit
+      }
+    }
+  }
+}

package/android/src/main/java/dev/poolse/callcore/CallMachine.kt

@@ -0,0 +1,292 @@
+package dev.poolse.callcore
+
+/**
+ * The call state machine — contract cv 1, CONTRACT.md §7.
+ *
+ * Pure: no I/O, no platform, no time. Events in, (state, effects) out.
+ * The adapters execute effects; the machine only decides. Its behavior
+ * is pinned by contracts/call-core/vectors.json, which the conformance
+ * test runs verbatim — change the vectors first, then this file.
+ *
+ * Lifecycle authority is the SERVER's (LiveKit-counted). This machine
+ * never counts participants to decide whether a call should end; it
+ * reacts to `RING_ENDED` and `CALL_FINISHED` and reports what the user
+ * did.
+ */
+
+enum class Phase { IDLE, RINGING_IN, RINGING_OUT, CONNECTING, ACTIVE, RECONNECTING, ENDED }
+
+enum class Direction { INCOMING, OUTGOING, JOINED }
+
+enum class EndReason {
+  LEFT, FINISHED, DECLINED_ALL, BUSY_ALL, NO_ANSWER, CANCELLED, CONNECTION_LOST, FAILED;
+
+  val wire: String get() = name.lowercase()
+}
+
+/** Everything the machine knows. Immutable; transitions return a new one. */
+data class MachineState(
+  val phase: Phase = Phase.IDLE,
+  val callId: String? = null,
+  val conversationId: String? = null,
+  val direction: Direction? = null,
+  val media: String = "audio",
+  val reason: EndReason? = null,
+  /** HTTP attempts made for the current connecting request (retry budget = 2). */
+  val httpAttempts: Int = 0,
+) {
+  companion object { val IDLE = MachineState() }
+}
+
+/** Inputs, named exactly as in the contract and vectors. */
+sealed interface Event {
+  /** A ring from push or socket — the machine treats them identically. */
+  data class Ring(
+    val callId: String,
+    val conversationId: String? = null,
+    val media: String = "audio",
+    /** Deadline already passed, or registry already finished. Never surface. */
+    val stale: Boolean = false,
+  ) : Event
+
+  data class RingEnded(val callId: String, val reason: String) : Event
+  data class CallFinished(val callId: String) : Event
+
+  data object UserAnswer : Event
+  data object UserDecline : Event
+  data class UserPlace(val callId: String, val conversationId: String? = null, val media: String = "audio") : Event
+  data class UserJoin(val callId: String, val conversationId: String? = null) : Event
+  data object UserHangup : Event
+
+  /** Server accepted answer/join/place. `created=false` on place means an existing live call (it became a join). */
+  data class HttpOk(val created: Boolean = true) : Event
+  data object HttpGone : Event
+  data object HttpTimeout : Event
+
+  data object MediaConnected : Event
+  data object MediaFailed : Event
+  data object MediaLost : Event
+  data object MediaRecovered : Event
+  data object RemoteJoined : Event
+
+  /** Caller side: every ring resolved without anyone joining. */
+  data class AllRingsResolved(val outcome: String) : Event
+
+  data object RingDeadline : Event
+  data object ReconnectBudgetElapsed : Event
+  data object LingerElapsed : Event
+}
+
+/** Abstract effects — each adapter maps them to its platform. */
+sealed interface Effect {
+  val wire: String
+
+  data object ShowRing : Effect { override val wire = "SHOW_RING" }
+  data object DismissRing : Effect { override val wire = "DISMISS_RING" }
+  data object RingtoneStart : Effect { override val wire = "RINGTONE_START" }
+  data object RingtoneStop : Effect { override val wire = "RINGTONE_STOP" }
+  data object RingbackStart : Effect { override val wire = "RINGBACK_START" }
+  data object RingbackStop : Effect { override val wire = "RINGBACK_STOP" }
+  data object HttpAnswer : Effect { override val wire = "HTTP_ANSWER" }
+  data object HttpJoin : Effect { override val wire = "HTTP_JOIN" }
+  data object HttpPlace : Effect { override val wire = "HTTP_PLACE" }
+  data object HttpDecline : Effect { override val wire = "HTTP_DECLINE" }
+  data class HttpDeclineBusy(val callId: String) : Effect { override val wire = "HTTP_DECLINE_BUSY:$callId" }
+  data object HttpHangup : Effect { override val wire = "HTTP_HANGUP" }
+  data object HttpReconnect : Effect { override val wire = "HTTP_RECONNECT" }
+  data object MediaJoin : Effect { override val wire = "MEDIA_JOIN" }
+  data object MediaLeave : Effect { override val wire = "MEDIA_LEAVE" }
+  data object CallSessionStart : Effect { override val wire = "CALL_SESSION_START" }
+  data object CallSessionStop : Effect { override val wire = "CALL_SESSION_STOP" }
+}
+
+data class Transition(val state: MachineState, val effects: List<Effect>)
+
+object CallMachine {
+
+  fun transition(s: MachineState, e: Event): Transition = when (e) {
+
+    is Event.Ring -> ring(s, e)
+
+    is Event.RingEnded ->
+      if (s.phase == Phase.RINGING_IN && e.callId == s.callId) {
+        Transition(MachineState.IDLE, listOf(Effect.RingtoneStop, Effect.DismissRing))
+      } else noop(s)
+
+    is Event.CallFinished ->
+      if (e.callId == s.callId) when (s.phase) {
+        Phase.ACTIVE, Phase.RECONNECTING, Phase.RINGING_OUT -> Transition(
+          s.copy(phase = Phase.ENDED, reason = EndReason.FINISHED),
+          buildList {
+            if (s.phase == Phase.RINGING_OUT) add(Effect.RingbackStop)
+            add(Effect.MediaLeave); add(Effect.CallSessionStop)
+          },
+        )
+        Phase.CONNECTING -> Transition(
+          s.copy(phase = Phase.ENDED, reason = EndReason.FINISHED),
+          listOf(Effect.CallSessionStop),
+        )
+        else -> noop(s)
+      } else noop(s)
+
+    Event.UserAnswer ->
+      if (s.phase == Phase.RINGING_IN) Transition(
+        s.copy(phase = Phase.CONNECTING, direction = Direction.INCOMING, httpAttempts = 1),
+        listOf(Effect.RingtoneStop, Effect.DismissRing, Effect.HttpAnswer, Effect.CallSessionStart),
+      ) else noop(s)
+
+    Event.UserDecline ->
+      if (s.phase == Phase.RINGING_IN) Transition(
+        MachineState.IDLE,
+        listOf(Effect.RingtoneStop, Effect.DismissRing, Effect.HttpDecline),
+      ) else noop(s)
+
+    is Event.UserPlace ->
+      if (s.phase == Phase.IDLE || s.phase == Phase.ENDED) Transition(
+        MachineState(
+          phase = Phase.CONNECTING, callId = e.callId, conversationId = e.conversationId,
+          direction = Direction.OUTGOING, media = e.media, httpAttempts = 1,
+        ),
+        listOf(Effect.HttpPlace, Effect.CallSessionStart),
+      ) else noop(s)
+
+    is Event.UserJoin ->
+      if (s.phase == Phase.IDLE || s.phase == Phase.ENDED) Transition(
+        MachineState(
+          phase = Phase.CONNECTING, callId = e.callId, conversationId = e.conversationId,
+          direction = Direction.JOINED, httpAttempts = 1,
+        ),
+        listOf(Effect.HttpJoin, Effect.CallSessionStart),
+      ) else noop(s)
+
+    Event.UserHangup -> when (s.phase) {
+      Phase.RINGING_OUT -> Transition(
+        s.copy(phase = Phase.ENDED, reason = EndReason.CANCELLED),
+        listOf(Effect.RingbackStop, Effect.MediaLeave, Effect.HttpHangup, Effect.CallSessionStop),
+      )
+      Phase.ACTIVE, Phase.RECONNECTING, Phase.CONNECTING -> Transition(
+        s.copy(phase = Phase.ENDED, reason = EndReason.LEFT),
+        listOf(Effect.MediaLeave, Effect.HttpHangup, Effect.CallSessionStop),
+      )
+      else -> noop(s)
+    }
+
+    is Event.HttpOk -> when {
+      s.phase != Phase.CONNECTING -> noop(s)
+      s.direction == Direction.OUTGOING && e.created -> Transition(
+        s.copy(phase = Phase.RINGING_OUT),
+        listOf(Effect.MediaJoin, Effect.RingbackStart),
+      )
+      s.direction == Direction.OUTGOING && !e.created -> Transition(
+        // Somebody's call was already live: our place collapsed into a join.
+        s.copy(direction = Direction.JOINED),
+        listOf(Effect.MediaJoin),
+      )
+      else -> Transition(s, listOf(Effect.MediaJoin))
+    }
+
+    Event.HttpGone -> when (s.phase) {
+      Phase.CONNECTING -> Transition(
+        s.copy(phase = Phase.ENDED, reason = EndReason.FINISHED),
+        listOf(Effect.CallSessionStop),
+      )
+      Phase.RECONNECTING -> Transition(
+        // Finished — or this device was superseded by the same user
+        // joining elsewhere. Either way: we are no longer in it.
+        s.copy(phase = Phase.ENDED, reason = EndReason.LEFT),
+        listOf(Effect.MediaLeave, Effect.CallSessionStop),
+      )
+      else -> noop(s)
+    }
+
+    Event.HttpTimeout ->
+      if (s.phase == Phase.CONNECTING && s.httpAttempts < 2) Transition(
+        s.copy(httpAttempts = s.httpAttempts + 1),
+        listOf(
+          when (s.direction) {
+            Direction.OUTGOING -> Effect.HttpPlace
+            Direction.JOINED -> Effect.HttpJoin
+            else -> Effect.HttpAnswer
+          },
+        ),
+      ) else noop(s) // out of retries: media join (or its absence) decides
+
+    Event.MediaConnected -> when (s.phase) {
+      Phase.CONNECTING -> Transition(s.copy(phase = Phase.ACTIVE), emptyList())
+      else -> noop(s) // ringing_out keeps ringing until a remote joins
+    }
+
+    Event.MediaFailed ->
+      if (s.phase == Phase.CONNECTING) Transition(
+        s.copy(phase = Phase.ENDED, reason = EndReason.FAILED),
+        listOf(Effect.HttpHangup, Effect.CallSessionStop),
+      ) else noop(s)
+
+    Event.MediaLost ->
+      if (s.phase == Phase.ACTIVE) Transition(
+        s.copy(phase = Phase.RECONNECTING),
+        listOf(Effect.HttpReconnect),
+      ) else noop(s)
+
+    Event.MediaRecovered ->
+      if (s.phase == Phase.RECONNECTING) Transition(s.copy(phase = Phase.ACTIVE), emptyList())
+      else noop(s)
+
+    Event.RemoteJoined ->
+      if (s.phase == Phase.RINGING_OUT) Transition(
+        s.copy(phase = Phase.ACTIVE),
+        listOf(Effect.RingbackStop),
+      ) else noop(s)
+
+    is Event.AllRingsResolved ->
+      if (s.phase == Phase.RINGING_OUT) Transition(
+        s.copy(
+          phase = Phase.ENDED,
+          reason = when (e.outcome) {
+            "busy_all" -> EndReason.BUSY_ALL
+            "no_answer" -> EndReason.NO_ANSWER
+            else -> EndReason.DECLINED_ALL
+          },
+        ),
+        listOf(Effect.RingbackStop, Effect.MediaLeave, Effect.HttpHangup, Effect.CallSessionStop),
+      ) else noop(s)
+
+    Event.RingDeadline ->
+      if (s.phase == Phase.RINGING_IN) Transition(
+        MachineState.IDLE,
+        listOf(Effect.RingtoneStop, Effect.DismissRing),
+      ) else noop(s)
+
+    Event.ReconnectBudgetElapsed ->
+      if (s.phase == Phase.RECONNECTING) Transition(
+        s.copy(phase = Phase.ENDED, reason = EndReason.CONNECTION_LOST),
+        listOf(Effect.MediaLeave, Effect.HttpHangup, Effect.CallSessionStop),
+      ) else noop(s)
+
+    Event.LingerElapsed ->
+      if (s.phase == Phase.ENDED) Transition(MachineState.IDLE, emptyList()) else noop(s)
+  }
+
+  private fun ring(s: MachineState, e: Event.Ring): Transition = when {
+    e.stale -> noop(s)
+
+    // Already showing this very ring (push + socket race): one surface.
+    s.phase == Phase.RINGING_IN && e.callId == s.callId -> noop(s)
+
+    // A fresh ring lands on idle — or over a lingering ended screen,
+    // which the new call simply replaces.
+    s.phase == Phase.IDLE || s.phase == Phase.ENDED -> Transition(
+      MachineState(
+        phase = Phase.RINGING_IN, callId = e.callId,
+        conversationId = e.conversationId, direction = Direction.INCOMING, media = e.media,
+      ),
+      listOf(Effect.ShowRing, Effect.RingtoneStart),
+    )
+
+    // Busy with another call, in any phase: auto-decline the newcomer,
+    // whose banner still offers Join later. (Contract §7, scenario s9.)
+    else -> Transition(s, listOf(Effect.HttpDeclineBusy(e.callId)))
+  }
+
+  private fun noop(s: MachineState) = Transition(s, emptyList())
+}