@poolse/react-native-calls 0.3.0 → 0.4.0

package/ios/Core/CallHttpClient.swift

@@ -0,0 +1,210 @@
+import Foundation
+
+/// The HTTP adapter for the contract's three token doors (CONTRACT.md §4).
+/// Direct port of android/.../CallHttpClient.kt. Every call is a bare REST
+/// request with a bearer token — no session state, no SDK coupling — so the
+/// core can answer a call on a cold launch with nothing but the push's grant.
+///
+/// Fire-and-forget methods (`decline`, `hangup`) retry transient failures a
+/// few times; request/response methods surface `HttpResult` to the runtime,
+/// which owns the retry policy for those (one retry).
+///
+/// Callbacks arrive on URLSession's delegate queue; the runtime hops them
+/// onto its own serial (main) queue.
+public final class CallHttpClient: HttpPort {
+
+  public static let MAX_BEST_EFFORT_RETRIES = 3
+
+  /// Read per request: a later `configure()` with another origin takes effect on the next call.
+  private let baseUrl: () -> String
+  private let session: URLSession
+
+  public init(baseUrl: @escaping () -> String, session: URLSession = CallHttpClient.defaultSession()) {
+    self.baseUrl = baseUrl
+    self.session = session
+  }
+
+  /// A call action must not hang the ring surface: 9 s total ceiling (6 s
+  /// without any data); the runtime retries answer/place once on top, and
+  /// both attempts fit inside its 20 s CONNECTING watchdog.
+  public static func defaultSession() -> URLSession {
+    let config = URLSessionConfiguration.ephemeral
+    config.timeoutIntervalForRequest = 6
+    config.timeoutIntervalForResource = 9
+    config.waitsForConnectivity = false
+    config.requestCachePolicy = .reloadIgnoringLocalCacheData
+    return URLSession(configuration: config)
+  }
+
+  public func answer(callId: String, grant: String, cb: @escaping (HttpResult) -> Void) {
+    post("calls/\(callId)/answer", token: grant, body: nil, current: nil, cb: cb)
+  }
+
+  public func join(callId: String, sessionToken: String, cb: @escaping (HttpResult) -> Void) {
+    post("calls/\(callId)/join", token: sessionToken, body: nil, current: nil, cb: cb)
+  }
+
+  public func place(conversationId: String, media: String, sessionToken: String,
+                    cb: @escaping (HttpResult) -> Void) {
+    post("conversations/\(conversationId)/calls", token: sessionToken, body: ["media": media], current: nil, cb: cb)
+  }
+
+  public func reconnect(current: CallSessionBundle, cb: @escaping (HttpResult) -> Void) {
+    post("calls/\(current.callId)/reconnect", token: current.controlToken, body: nil, current: current, cb: cb)
+  }
+
+  public func decline(callId: String, auth: String, busy: Bool) {
+    postBestEffort("calls/\(callId)/decline", token: auth, body: ["reason": busy ? "busy" : "declined"], attempt: 0)
+  }
+
+  public func hangup(callId: String, controlToken: String) {
+    postBestEffort("calls/\(callId)/hangup", token: controlToken, body: nil, attempt: 0)
+  }
+
+  // MARK: request/response
+
+  private func post(_ path: String, token: String, body: [String: Any]?, current: CallSessionBundle?,
+                    cb: @escaping (HttpResult) -> Void) {
+    guard let req = request(path, token: token, body: body) else {
+      // A malformed base URL is a configuration error, not a timeout.
+      cb(.failed(code: "bad_url"))
+      return
+    }
+    session.dataTask(with: req) { data, response, error in
+      if error != nil {
+        cb(.timeout)
+        return
+      }
+      guard let http = response as? HTTPURLResponse else {
+        cb(.timeout)
+        return
+      }
+      let payload = data.flatMap { String(data: $0, encoding: .utf8) }
+      cb(CallHttpClient.classify(code: http.statusCode, payload: payload, current: current))
+    }.resume()
+  }
+
+  // MARK: fire-and-forget with bounded retry
+
+  private func postBestEffort(_ path: String, token: String, body: [String: Any]?, attempt: Int) {
+    guard let req = request(path, token: token, body: body) else { return }
+    session.dataTask(with: req) { [weak self] _, response, error in
+      guard let self = self else { return }
+      let retry: Bool
+      if error != nil || !(response is HTTPURLResponse) {
+        retry = true
+      } else {
+        let code = (response as! HTTPURLResponse).statusCode
+        // 2xx and 4xx are both terminal here. Only transient 5xx/408/429 retries.
+        retry = code == 408 || code == 429 || (500...599).contains(code)
+      }
+      if retry && attempt < CallHttpClient.MAX_BEST_EFFORT_RETRIES {
+        self.postBestEffort(path, token: token, body: body, attempt: attempt + 1)
+      }
+    }.resume()
+  }
+
+  private func request(_ path: String, token: String, body: [String: Any]?) -> URLRequest? {
+    var base = baseUrl()
+    while base.hasSuffix("/") { base.removeLast() }
+    guard let url = URL(string: "\(base)/v1/\(path)"), url.scheme != nil, url.host != nil else { return nil }
+    var req = URLRequest(url: url)
+    req.httpMethod = "POST"
+    req.setValue("Bearer \(token)", forHTTPHeaderField: "Authorization")
+    req.setValue("application/json", forHTTPHeaderField: "Accept")
+    req.setValue("application/json; charset=utf-8", forHTTPHeaderField: "Content-Type")
+    req.httpBody = (try? JSONSerialization.data(withJSONObject: body ?? [String: Any]())) ?? Data("{}".utf8)
+    req.timeoutInterval = 9
+    return req
+  }
+
+  // MARK: pure classification (unit tested without a network)
+
+  private struct ParseError: Error { let what: String }
+
+  /// Status + body → HttpResult (CONTRACT.md §4).
+  /// 2xx that will not parse → failed("bad_body"); 404/410 → gone;
+  /// 401/403 → authFailed; 503 → failed; 408/429/5xx → timeout; other → failed.
+  public static func classify(code: Int, payload: String?, current: CallSessionBundle? = nil) -> HttpResult {
+    switch code {
+    case 200...299:
+      if let b = try? parseBundle(payload, current: current) { return .ok(b) }
+      return .failed(code: "bad_body")
+    case 404, 410:
+      return .gone
+    case 401, 403:
+      return .authFailed(code: errorCode(payload) ?? "http_\(code)")
+    case 503:
+      return .failed(code: errorCode(payload) ?? "http_503")
+    case 408, 429, 500...599:
+      return .timeout
+    default:
+      return .failed(code: errorCode(payload) ?? "http_\(code)")
+    }
+  }
+
+  /// One parser for answer, join, place AND reconnect. An older server's
+  /// reconnect answered only `{livekit:{url,token}}` (maybe a fresh
+  /// `control_token`); with `current`, that is applied onto the existing bundle.
+  public static func parseBundle(_ payload: String?, current: CallSessionBundle? = nil) throws -> CallSessionBundle {
+    guard let payload = payload, let data = payload.data(using: .utf8),
+          let root = (try? JSONSerialization.jsonObject(with: data)) as? [String: Any]
+    else { throw ParseError(what: "empty or non-object body") }
+    guard let livekit = root["livekit"] as? [String: Any] else { throw ParseError(what: "no livekit") }
+    let call = root["call"] as? [String: Any]
+    guard let call = call else {
+      guard let current = current else { throw ParseError(what: "bundle without call") }
+      var b = current
+      b.livekitUrl = optString(livekit, "url") ?? current.livekitUrl
+      b.livekitToken = try getString(livekit, "token")
+      b.controlToken = optString(root, "control_token") ?? current.controlToken
+      return b
+    }
+    guard let controlToken = optString(root, "control_token") ?? current?.controlToken else {
+      throw ParseError(what: "bundle without control_token")
+    }
+    return CallSessionBundle(
+      callId: try getString(call, "id"),
+      conversationId: try getString(call, "conversation_id"),
+      conversationName: optString(call, "conversation_name") ?? current?.conversationName,
+      media: optString(call, "media") ?? current?.media ?? "audio",
+      created: optBool(root, "created", fallback: true),
+      livekitUrl: try getString(livekit, "url"),
+      livekitToken: try getString(livekit, "token"),
+      controlToken: controlToken
+    )
+  }
+
+  /// The server's envelope is `{"error":{"code":"…"}}`; tolerate a bare string too.
+  public static func errorCode(_ payload: String?) -> String? {
+    guard let payload = payload, let data = payload.data(using: .utf8),
+          let root = (try? JSONSerialization.jsonObject(with: data)) as? [String: Any]
+    else { return nil }
+    if let err = root["error"] as? [String: Any] { return optString(err, "code") ?? nil }
+    return optString(root, "error")
+  }
+
+  /// org.json `optString`-or-null semantics: present, non-null, a String, non-empty.
+  private static func optString(_ o: [String: Any], _ key: String) -> String? {
+    guard let s = o[key] as? String, !s.isEmpty else { return nil }
+    return s
+  }
+
+  /// org.json (Android) `getString`: required, non-null; numbers/bools coerce to text.
+  private static func getString(_ o: [String: Any], _ key: String) throws -> String {
+    guard let v = o[key], !(v is NSNull) else { throw ParseError(what: "missing \(key)") }
+    if let s = v as? String { return s }
+    if let n = v as? NSNumber { return n.stringValue }
+    throw ParseError(what: "bad \(key)")
+  }
+
+  /// org.json `optBoolean(key, fallback)`: a Bool, or "true"/"false" text.
+  private static func optBool(_ o: [String: Any], _ key: String, fallback: Bool) -> Bool {
+    if let n = o[key] as? NSNumber, CFGetTypeID(n) == CFBooleanGetTypeID() { return n.boolValue }
+    if let s = (o[key] as? String)?.lowercased() {
+      if s == "true" { return true }
+      if s == "false" { return false }
+    }
+    return fallback
+  }
+}

package/ios/Core/CallMachine.swift

@@ -0,0 +1,304 @@
+import Foundation
+
+// The call state machine — contract cv 1, CONTRACT.md §7. Direct port of
+// android/.../callcore/CallMachine.kt. Pure: no I/O, no platform, no time.
+// Pinned by contracts/call-core/vectors.json — change the vectors first.
+
+/// Inputs, named exactly as in the contract and vectors.
+public enum Event: Equatable {
+  /// A ring from push or socket — treated identically. `stale`: deadline passed. Never surface.
+  case ring(callId: String, conversationId: String? = nil, media: String = "audio", stale: Bool = false)
+  case ringEnded(callId: String, reason: String)
+  /// The server finished the call; `reason` only colours an unanswered caller's ended screen.
+  case callFinished(callId: String, reason: String? = nil)
+  case userAnswer
+  case userDecline
+  case userPlace(callId: String, conversationId: String? = nil, media: String = "audio")
+  case userJoin(callId: String, conversationId: String? = nil)
+  case userHangup
+  /// Server accepted answer/join/place. `created=false` on place: an existing live call (became a join).
+  case httpOk(created: Bool = true)
+  case httpGone
+  case httpTimeout
+  /// Terminal refusal that is NOT "the call is over" (401/403, 503, unparseable 2xx).
+  case httpFailed(code: String = "failed")
+  case mediaConnected
+  case mediaFailed
+  case mediaLost
+  /// The SFU is recovering on its own. Show it; do not rejoin.
+  case mediaReconnecting
+  case mediaRecovered
+  case remoteJoined
+  /// Caller side: every ring resolved without anyone joining.
+  case allRingsResolved(outcome: String)
+  case ringDeadline
+  case reconnectBudgetElapsed
+  /// CONNECTING watchdog.
+  case connectTimeout
+  case lingerElapsed
+}
+
+/// Abstract effects — each adapter maps them to its platform.
+public enum Effect: Equatable {
+  case showRing, dismissRing, ringtoneStart, ringtoneStop, ringbackStart, ringbackStop
+  case httpAnswer, httpJoin, httpPlace, httpDecline
+  case httpDeclineBusy(callId: String)
+  case httpHangup, httpReconnect, mediaJoin, mediaLeave, callSessionStart, callSessionStop
+
+  public var wire: String {
+    switch self {
+    case .showRing: return "SHOW_RING"
+    case .dismissRing: return "DISMISS_RING"
+    case .ringtoneStart: return "RINGTONE_START"
+    case .ringtoneStop: return "RINGTONE_STOP"
+    case .ringbackStart: return "RINGBACK_START"
+    case .ringbackStop: return "RINGBACK_STOP"
+    case .httpAnswer: return "HTTP_ANSWER"
+    case .httpJoin: return "HTTP_JOIN"
+    case .httpPlace: return "HTTP_PLACE"
+    case .httpDecline: return "HTTP_DECLINE"
+    case .httpDeclineBusy(let callId): return "HTTP_DECLINE_BUSY:\(callId)"
+    case .httpHangup: return "HTTP_HANGUP"
+    case .httpReconnect: return "HTTP_RECONNECT"
+    case .mediaJoin: return "MEDIA_JOIN"
+    case .mediaLeave: return "MEDIA_LEAVE"
+    case .callSessionStart: return "CALL_SESSION_START"
+    case .callSessionStop: return "CALL_SESSION_STOP"
+    }
+  }
+}
+
+public struct Transition: Equatable {
+  public let state: MachineState
+  public let effects: [Effect]
+  public init(_ state: MachineState, _ effects: [Effect]) {
+    self.state = state
+    self.effects = effects
+  }
+}
+
+private extension MachineState {
+  func with(phase: Phase? = nil, reason: EndReason?? = nil, direction: Direction?? = nil,
+            httpAttempts: Int? = nil) -> MachineState {
+    var c = self
+    if let phase = phase { c.phase = phase }
+    if let reason = reason { c.reason = reason }
+    if let direction = direction { c.direction = direction }
+    if let httpAttempts = httpAttempts { c.httpAttempts = httpAttempts }
+    return c
+  }
+}
+
+public enum CallMachine {
+
+  public static func transition(_ s: MachineState, _ e: Event) -> Transition {
+    switch e {
+
+    case let .ring(callId, conversationId, media, stale):
+      return ring(s, callId: callId, conversationId: conversationId, media: media, stale: stale)
+
+    case let .ringEnded(callId, _):
+      if s.phase == .ringingIn && callId == s.callId {
+        return Transition(.IDLE, [.ringtoneStop, .dismissRing])
+      }
+      return noop(s)
+
+    case let .callFinished(callId, reason):
+      guard callId == s.callId else { return noop(s) }
+      switch s.phase {
+      case .ringingIn:
+        return Transition(.IDLE, [.ringtoneStop, .dismissRing])
+      case .ringingOut:
+        return Transition(s.with(phase: .ended, reason: .some(ringOutcome(reason))),
+                          [.ringbackStop, .mediaLeave, .callSessionStop])
+      case .active, .reconnecting, .connecting:
+        return Transition(s.with(phase: .ended, reason: .some(.finished)), [.mediaLeave, .callSessionStop])
+      case .ended:
+        let outcome = ringOutcome(reason)
+        if s.direction == .outgoing && s.reason == .finished && outcome != .finished {
+          return Transition(s.with(reason: .some(outcome)), [])
+        }
+        return noop(s)
+      default:
+        return noop(s)
+      }
+
+    case .userAnswer:
+      if s.phase == .ringingIn {
+        return Transition(s.with(phase: .connecting, direction: .some(.incoming), httpAttempts: 1),
+                          [.ringtoneStop, .dismissRing, .httpAnswer, .callSessionStart])
+      }
+      return noop(s)
+
+    case .userDecline:
+      if s.phase == .ringingIn {
+        return Transition(.IDLE, [.ringtoneStop, .dismissRing, .httpDecline])
+      }
+      return noop(s)
+
+    case let .userPlace(callId, conversationId, media):
+      if s.phase == .idle || s.phase == .ended {
+        return Transition(MachineState(phase: .connecting, callId: callId, conversationId: conversationId,
+                                       direction: .outgoing, media: media, httpAttempts: 1),
+                          [.httpPlace, .callSessionStart])
+      }
+      return noop(s)
+
+    case let .userJoin(callId, conversationId):
+      if s.phase == .idle || s.phase == .ended {
+        return Transition(MachineState(phase: .connecting, callId: callId, conversationId: conversationId,
+                                       direction: .joined, httpAttempts: 1),
+                          [.httpJoin, .callSessionStart])
+      }
+      return noop(s)
+
+    case .userHangup:
+      switch s.phase {
+      case .ringingOut:
+        return Transition(s.with(phase: .ended, reason: .some(.cancelled)),
+                          [.ringbackStop, .mediaLeave, .httpHangup, .callSessionStop])
+      case .active, .reconnecting, .connecting:
+        return Transition(s.with(phase: .ended, reason: .some(.left)),
+                          [.mediaLeave, .httpHangup, .callSessionStop])
+      default:
+        return noop(s)
+      }
+
+    case let .httpOk(created):
+      if s.phase != .connecting { return noop(s) }
+      if s.direction == .outgoing && created {
+        return Transition(s.with(phase: .ringingOut), [.mediaJoin, .ringbackStart])
+      }
+      if s.direction == .outgoing && !created {
+        return Transition(s.with(direction: .some(.joined)), [.mediaJoin])
+      }
+      return Transition(s, [.mediaJoin])
+
+    case .httpGone:
+      switch s.phase {
+      case .connecting:
+        return Transition(s.with(phase: .ended, reason: .some(.finished)), [.callSessionStop])
+      case .reconnecting:
+        return Transition(s.with(phase: .ended, reason: .some(.left)), [.mediaLeave, .callSessionStop])
+      default:
+        return noop(s)
+      }
+
+    case .httpTimeout:
+      if s.phase != .connecting { return noop(s) }
+      if s.httpAttempts < 2 {
+        let retry: Effect
+        switch s.direction {
+        case .outgoing?: retry = .httpPlace
+        case .joined?: retry = .httpJoin
+        default: retry = .httpAnswer
+        }
+        return Transition(s.with(httpAttempts: s.httpAttempts + 1), [retry])
+      }
+      return Transition(s.with(phase: .ended, reason: .some(.failed)), [.httpHangup, .callSessionStop])
+
+    case .httpFailed:
+      switch s.phase {
+      case .connecting:
+        return Transition(s.with(phase: .ended, reason: .some(.failed)), [.httpHangup, .callSessionStop])
+      case .reconnecting:
+        return Transition(s.with(phase: .ended, reason: .some(.failed)), [.mediaLeave, .callSessionStop])
+      default:
+        return noop(s)
+      }
+
+    case .connectTimeout:
+      if s.phase == .connecting {
+        return Transition(s.with(phase: .ended, reason: .some(.failed)),
+                          [.mediaLeave, .httpHangup, .callSessionStop])
+      }
+      return noop(s)
+
+    case .mediaConnected:
+      switch s.phase {
+      case .connecting, .reconnecting: return Transition(s.with(phase: .active), [])
+      default: return noop(s)
+      }
+
+    case .mediaFailed:
+      switch s.phase {
+      case .connecting:
+        return Transition(s.with(phase: .ended, reason: .some(.failed)), [.httpHangup, .callSessionStop])
+      case .ringingOut:
+        return Transition(s.with(phase: .ended, reason: .some(.failed)),
+                          [.ringbackStop, .mediaLeave, .httpHangup, .callSessionStop])
+      default:
+        return noop(s)
+      }
+
+    case .mediaLost:
+      switch s.phase {
+      case .active: return Transition(s.with(phase: .reconnecting), [.httpReconnect])
+      case .reconnecting: return Transition(s, [.httpReconnect])
+      default: return noop(s)
+      }
+
+    case .mediaReconnecting:
+      return s.phase == .active ? Transition(s.with(phase: .reconnecting), []) : noop(s)
+
+    case .mediaRecovered:
+      return s.phase == .reconnecting ? Transition(s.with(phase: .active), []) : noop(s)
+
+    case .remoteJoined:
+      return s.phase == .ringingOut ? Transition(s.with(phase: .active), [.ringbackStop]) : noop(s)
+
+    case let .allRingsResolved(outcome):
+      guard s.phase == .ringingOut else { return noop(s) }
+      let reason: EndReason
+      switch outcome {
+      case "busy_all": reason = .busyAll
+      case "no_answer": reason = .noAnswer
+      case "cancelled": reason = .cancelled
+      default: reason = .declinedAll
+      }
+      return Transition(s.with(phase: .ended, reason: .some(reason)),
+                        [.ringbackStop, .mediaLeave, .httpHangup, .callSessionStop])
+
+    case .ringDeadline:
+      return s.phase == .ringingIn ? Transition(.IDLE, [.ringtoneStop, .dismissRing]) : noop(s)
+
+    case .reconnectBudgetElapsed:
+      if s.phase == .reconnecting {
+        return Transition(s.with(phase: .ended, reason: .some(.connectionLost)),
+                          [.mediaLeave, .httpHangup, .callSessionStop])
+      }
+      return noop(s)
+
+    case .lingerElapsed:
+      return s.phase == .ended ? Transition(.IDLE, []) : noop(s)
+    }
+  }
+
+  private static func ring(_ s: MachineState, callId: String, conversationId: String?, media: String,
+                           stale: Bool) -> Transition {
+    if stale { return noop(s) }
+    // Already showing this very ring (push + socket race): one surface.
+    if s.phase == .ringingIn && callId == s.callId { return noop(s) }
+    // A fresh ring on idle — or over a lingering ended screen.
+    if s.phase == .idle || s.phase == .ended {
+      return Transition(MachineState(phase: .ringingIn, callId: callId, conversationId: conversationId,
+                                     direction: .incoming, media: media),
+                        [.showRing, .ringtoneStart])
+    }
+    // Busy with another call: auto-decline the newcomer.
+    return Transition(s, [.httpDeclineBusy(callId: callId)])
+  }
+
+  /// A finish push's reason, read as the caller's unanswered outcome.
+  private static func ringOutcome(_ reason: String?) -> EndReason {
+    switch reason {
+    case "no_answer"?, "timeout"?: return .noAnswer
+    case "declined_all"?, "declined"?: return .declinedAll
+    case "busy_all"?: return .busyAll
+    case "cancelled"?: return .cancelled
+    default: return .finished
+    }
+  }
+
+  private static func noop(_ s: MachineState) -> Transition { Transition(s, []) }
+}

package/ios/Core/PORTS_READY.md

@@ -0,0 +1,93 @@
+# iOS call core — ports & runtime API (ready to code against)
+
+Swift port of `android/.../callcore/{Ports,CallMachine,CallCoreRuntime}.kt`.
+Foundation only, main-thread confined, no Sendable. All types `public`.
+
+## Ports (ios/Core/Ports.swift)
+
+```swift
+protocol HttpPort: AnyObject {
+  func answer(callId: String, grant: String, cb: @escaping (HttpResult) -> Void)
+  func join(callId: String, sessionToken: String, cb: @escaping (HttpResult) -> Void)
+  func place(conversationId: String, media: String, sessionToken: String, cb: @escaping (HttpResult) -> Void)
+  func decline(callId: String, auth: String, busy: Bool)
+  func hangup(callId: String, controlToken: String)
+  func reconnect(current: CallSessionBundle, cb: @escaping (HttpResult) -> Void)
+}
+enum HttpResult { case ok(CallSessionBundle), gone, timeout, authFailed(code: String), failed(code: String) }
+struct CallSessionBundle { callId, conversationId, conversationName?, media, created, livekitUrl, livekitToken, controlToken }
+
+protocol MediaPort: AnyObject {
+  func join(bundle: CallSessionBundle); func leave()
+  func setMuted(_ muted: Bool); func setCamera(_ on: Bool); func switchCamera(); func setSpeaker(_ on: Bool)
+}
+protocol RingSurfacePort: AnyObject {
+  func show(ring: RingContext); func dismiss(callId: String)
+  func ringtoneStart(); func ringtoneStop(); func ringbackStart(); func ringbackStop()
+}
+struct RingContext { callId, conversationId, conversationName?, callerName?, media, grant, ringDeadlineEpochMs: Int64 }
+protocol CallSessionPort: AnyObject { func start(callId: String, media: String); func stop() }
+protocol SnapshotSink: AnyObject { func emit(state: MachineState) }   // BlockSnapshotSink { state in ... } helper
+protocol TimerPort: AnyObject {
+  func nowMs() -> Int64
+  func schedule(key: String, delayMs: Int64, fire: @escaping () -> Void)  // same key replaces
+  func cancel(key: String)
+}
+// State values: Phase (.idle .ringingIn .ringingOut .connecting .active .reconnecting .ended),
+// Direction (.incoming .outgoing .joined), EndReason (.left .finished .declinedAll .busyAll
+// .noAnswer .cancelled .connectionLost .failed; `.wire` = "declined_all" etc.),
+// MachineState { phase, callId?, conversationId?, direction?, media, reason?, httpAttempts }
+```
+
+Provided implementations in Core: `CallHttpClient` (HttpPort, URLSession),
+`MainQueueTimerPort()` (TimerPort on DispatchQueue.main, epoch nowMs), `BlockSnapshotSink { state in }`.
+
+## Runtime (ios/Core/CallCoreRuntime.swift)
+
+```swift
+let rt = CallCoreRuntime(
+  http: HttpPort, media: MediaPort, surface: RingSurfacePort,
+  session: CallSessionPort, timers: TimerPort, sink: SnapshotSink,
+  executor: ((@escaping () -> Void) -> Void)? = nil)  // default: inline if on main thread, else DispatchQueue.main.async
+
+rt.currentState() -> MachineState
+rt.conversationName: String?          // bundle's, else the ring's (main thread)
+rt.isResolved(_ callId: String) -> Bool
+rt.post(_ block: @escaping () -> Void)
+
+// inputs
+rt.onRing(_ ctx: RingContext)          // push (PushKit) or socket — same path
+rt.onRingEnded(callId:reason:)
+rt.onCallFinished(callId:reason:)      // reason: String? = nil
+rt.answer(); rt.decline(); rt.hangUp()
+rt.place(conversationId:media:sessionToken:)
+rt.join(callId:conversationId:sessionToken:)   // conversationId: String?
+rt.allRingsResolved(_ outcome: String)
+rt.onMediaConnected(); rt.onMediaFailed(); rt.onMediaLost()
+rt.onMediaReconnecting(); rt.onMediaRecovered(); rt.onRemoteJoined()
+rt.setMuted(_:); rt.setCamera(_:); rt.switchCamera(); rt.setSpeaker(_:)
+rt.reemit()                            // re-emit current state (roster/route changed)
+```
+
+Constants: `CallCoreRuntime.ENDED_LINGER_MS` (2500), `RECONNECT_BUDGET_MS` (25000),
+`CONNECT_WATCHDOG_MS` (20000), `RING_OUT_BACKSTOP_MS` (75000), `CLOCK_SLACK_MS` (10000), `RESOLVED_LRU` (32).
+
+The sink receives the MachineState after every change; IDLE means "no call" (emit `snapshot: null`).
+Ended state lingers 2.5 s, then IDLE is emitted.
+
+## HTTP client (ios/Core/CallHttpClient.swift)
+
+```swift
+CallHttpClient(baseUrl: @escaping () -> String, session: URLSession = CallHttpClient.defaultSession())
+// baseUrl read per request (staging/prod switch). 9 s total timeout. Static classify/parseBundle/errorCode are pure.
+```
+
+## Snapshot (ios/Core/SnapshotEncoding.swift)
+
+```swift
+struct SnapshotParticipant { userId, externalId, speaking, muted, cameraOn }
+MachineState.toSnapshot(conversationName: String? = nil,
+  participants: [SnapshotParticipant] = [], audioRoute: String = "earpiece",
+  mutedSelf: Bool = false, cameraOn: Bool = false, cameraFacing: String? = nil) -> [String: Any]?
+// nil for IDLE. conversationName nil -> NSNull; reason / cameraFacing omitted when nil.
+```