Hum Rahi

────────────────────────────────────────────────────────────
US-033.BE.1 — WebRTC Failure Detection & Phone Call Fallback Orchestration
────────────────────────────────────────────────────────────

Role
As a backend developer on Ham Rahi,
I need to monitor WebRTC session establishment after SOS activation
and automatically trigger a direct phone call to the citizen if the
stream fails to become active within 5 seconds,
So that Priya is never left in silence during a real emergency simply
because of a network or WebRTC negotiation failure.

User Story
As Priya,
I want the system to automatically call my registered phone number
if the audio connection to the police operator fails to establish
within 5 seconds of my SOS activating,
So that I always have a voice channel to emergency services even
when WebRTC cannot connect, without me having to do anything.

In-Scope

• Starting a 5-second watchdog timer at the moment the SOS
  activation event is received (the same moment US-030.BE.1 begins
  WebRTC signalling)
• Monitoring WebRTC session state: the watchdog is cancelled if the
  audio stream is confirmed active within 5 seconds
• Triggering the phone call fallback if the watchdog expires without
  a confirmed active stream; the fallback must initiate without any
  action from the citizen or the operator
• Integrating with a telephony provider (IVR / programmable voice
  API) to place an outbound call to the citizen's verified phone
  number registered in their Ham Rahi profile
• Routing the fallback call to the assigned police panel operator's
  designated duty phone number, creating a direct voice bridge
  between citizen and operator
• Persisting the fallback event to the SOS session record: timestamp
  of WebRTC failure detection, timestamp of call initiation, call
  provider reference ID, and fallback reason code
• Notifying the police panel in real time that the session has
  switched to phone fallback: updating the SOS alert card state
  via the existing WebSocket channel so ASI Akram sees the mode
  change without ambiguity
• Handling the case where the outbound call to the citizen is not
  answered within a defined ring timeout: logging the unanswered
  attempt and escalating to a supervisor alert
• Handling the case where the operator's duty phone is unavailable:
  falling back to the duty supervisor number per the same routing
  rules defined in US-030.BE.1
• Ensuring the fallback does not trigger if WebRTC recovers and
  the stream becomes active before the watchdog expires — no
  duplicate channel activation
• Allowing the WebRTC session attempt to be cleanly abandoned once
  the fallback call is confirmed connected, releasing signalling
  resources without leaving orphaned sessions

Out-of-Scope

• WebRTC signalling logic itself (US-030.BE.1)
• STUN/TURN infrastructure (US-030.INFRA.1)
• Telephony provider infrastructure provisioning (US-033.INFRA.1)
• Citizen-facing UI indication of the fallback (separate FE story)
• Police panel card state update rendering (US-032.FE.1 consumes
  the WebSocket event emitted here)
• Two-way audio upgrade authority (Phase 2, operator-restricted)
• Manual fallback triggered by the operator (Phase 2)
• SMS or push notification as a fallback channel (Phase 2
  consideration if both WebRTC and call fail)

Acceptance Criteria

AC1 A 5-second watchdog timer starts at the exact moment the SOS
activation event is received; the timer is cancelled without
side effects if the WebRTC audio stream is confirmed active
before expiry.

AC2 If the watchdog expires without a confirmed active WebRTC
stream, the backend initiates an outbound phone call to the
citizen's verified registered number within 2 seconds of
watchdog expiry, without any manual intervention.

AC3 The outbound call routes the citizen to the assigned police
panel operator's designated duty phone, creating a direct
voice bridge; operator routing follows the same fallback
rules defined in US-030.BE.1 if the primary operator is
unavailable.

AC4 The SOS session record is updated at the moment of fallback
trigger with: WebRTC failure timestamp, call initiation
timestamp, telephony provider call reference ID, and a
fallback reason code distinguishing timeout from signalling
error.

AC5 A WebSocket notification is emitted to the police panel within
1 second of fallback initiation, updating the SOS session
state to phone-fallback-active so the operator's alert card
reflects the mode change in real time.

AC6 If the outbound call to the citizen is not answered within the
defined ring timeout, the unanswered attempt is logged against
the session record and a supervisor escalation alert is raised.

AC7 If the operator's duty phone is unavailable, the call routes
to the duty supervisor number; this fallback chain is
attempted before the unanswered escalation in AC6 is raised.

AC8 If WebRTC becomes active in the same instant the watchdog
fires — a race condition — the system resolves deterministically:
if the stream is confirmed active before the outbound call
connects, the call is cancelled and no fallback record is
written; if the call connects first, the WebRTC session is
abandoned cleanly.

AC9 Once the fallback call is confirmed connected, the WebRTC
signalling session is terminated cleanly; no orphaned
signalling resources remain on the server.

AC10 The fallback mechanism does not trigger for early-release
cancellations (US-029) or any session that was never fully
activated; the watchdog must only start on a confirmed
activation event.

Definition of Done

• Watchdog timer start and cancellation on WebRTC success confirmed
  by integration test
• Fallback call initiation within 2 seconds of watchdog expiry
  confirmed in staging with telephony provider sandbox
• Operator duty phone routing confirmed including supervisor
  fallback when primary is unavailable
• Session record updated with all required fallback fields confirmed
  by DB inspection in test
• WebSocket panel notification within 1 second of fallback
  confirmed by integration test
• Unanswered call timeout and supervisor escalation confirmed
• Race condition test (WebRTC activates at watchdog boundary)
  documented and passing
• Clean WebRTC session teardown after connected call confirmed
• No fallback triggered for early-release sessions confirmed
• No open P1 or P2 bugs
• Code reviewed and merged