@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/callkit-voip/SKILL.md

@@ -1,76 +1,62 @@
 ---
 name: callkit-voip
-description: "Implement VoIP calling with CallKit and PushKit. Use when building incoming/outgoing call flows, registering for VoIP push notifications, configuring CXProvider and CXCallController, handling call actions, coordinating audio sessions, or creating Call Directory extensions for caller ID and call blocking."
+description: "CallKit and PushKit VoIP calling: CXProvider and CXCallController, incoming and outgoing call flows, call actions, VoIP push registration and reporting, call audio sessions, Call Directory caller ID and blocking. Use when implementing VoIP calls or VoIP push handling."
 metadata:
-  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
+  source: multi-agent-pipeline
 ---
 
-# CallKit
+# CallKit and PushKit VoIP
 
-Build VoIP calling features that integrate with the native iOS call UI using
-CallKit and PushKit. Covers incoming/outgoing call flows, VoIP push
-registration, audio session coordination, and call directory extensions.
-Targets Swift 6.3 / iOS 26+.
+CallKit puts an app's VoIP calls into the same system call UI that cellular
+calls use: the lock-screen answer slider, the in-call screen, Recents and
+Bluetooth controls. PushKit wakes the app when a call arrives. Everything here
+targets Swift 6.3 and iOS 26 or later unless a line names another release.
 
-## Contents
-
-- [Setup](#setup)
-- [Provider Configuration](#provider-configuration)
-- [Incoming Call Flow](#incoming-call-flow)
-- [Outgoing Call Flow](#outgoing-call-flow)
-- [PushKit VoIP Registration](#pushkit-voip-registration)
-- [Audio Session Coordination](#audio-session-coordination)
-- [Call Directory Extension and Manager](#call-directory-extension-and-manager)
-- [Common Mistakes](#common-mistakes)
-- [Review Checklist](#review-checklist)
-- [References](#references)
+Rotating APNs auth keys and everyday remote-notification registration live
+in `push-notifications`. This skill starts at the VoIP push type.
 
 ## Setup
 
-### Project Configuration
+### Project configuration
 
-1. Enable the **Voice over IP** background mode in Signing & Capabilities
-2. Add the **Push Notifications** capability
-3. For call directory extensions, add a **Call Directory Extension** target
+1. Signing & Capabilities: turn on Background Modes and tick **Voice over IP**.
+2. Push Notifications must also appear in the capability list.
+3. Caller ID or blocking lists need a separate target of type Call Directory Extension.
 
-### Key Types
+### The types you touch
 
-| Type | Role |
-|---|---|
-| `CXProvider` | Reports calls to the system, receives call actions |
-| `CXCallController` | Requests call actions (start, end, hold, mute) |
-| `CXCallUpdate` | Describes call metadata (caller name, video, handle) |
-| `CXProviderDelegate` | Handles system call actions and audio session events |
-| `PKPushRegistry` | Registers for and receives VoIP push notifications |
-| `PKVoIPPushMetadata` | iOS 26.4+ metadata that says whether a VoIP push must be reported |
+| Type | Job |
+| --- | --- |
+| `CXProvider` | Tells the system about calls and receives the actions the system wants performed |
+| `CXCallController` | Asks the system to perform an action: start, end, hold, mute |
+| `CXCallUpdate` | Describes a call: caller name, handle, video |
+| `CXProviderDelegate` | Performs call actions and receives audio session activation |
+| `PKPushRegistry` | Registers for VoIP pushes and delivers them |
+| `PKVoIPPushMetadata` | iOS 26.4+: says whether a given VoIP push has to be reported |
 
-## Provider Configuration
+## Provider configuration
 
-Create a single `CXProvider` at app launch and keep it alive for the app
-lifetime. Configure it with a `CXProviderConfiguration` that describes your
-calling capabilities.
+Build one `CXProvider` when the app launches and keep that instance until the
+process dies. Creating a second provider or recreating it per call confuses the
+system about which calls exist.
 
 ```swift
 import CallKit
 
-/// CXProvider dispatches all delegate calls to the queue passed to `setDelegate(_:queue:)`.
-/// The `let` properties are initialized once and never mutated, making this type
-/// safe to share across concurrency domains despite @unchecked Sendable.
-final class CallManager: NSObject, @unchecked Sendable {
-    static let shared = CallManager()
+@MainActor
+final class PhoneLine: NSObject {
+    static let shared = PhoneLine()
 
     let provider: CXProvider
-    let callController = CXCallController()
+    let controller = CXCallController()
 
-    private override init() {
+    override init() {
         let config = CXProviderConfiguration()
-        config.localizedName = "My VoIP App"
         config.supportsVideo = true
-        config.maximumCallsPerCallGroup = 1
         config.maximumCallGroups = 2
+        config.maximumCallsPerCallGroup = 1
         config.supportedHandleTypes = [.phoneNumber, .emailAddress]
         config.includesCallsInRecents = true
-
         provider = CXProvider(configuration: config)
         super.init()
         provider.setDelegate(self, queue: nil)
@@ -78,204 +64,188 @@ final class CallManager: NSObject, @unchecked Sendable {
 }
 ```
 
-## Incoming Call Flow
+`PhoneLine` is `@MainActor` because every delegate callback arrives on the
+queue passed to `setDelegate(_:queue:)`, and `nil` means the main queue. The
+delegate conformance below is `@preconcurrency`, so those callbacks run as
+main-actor code and the `Task` each one starts inherits that isolation. That is
+what lets a `Task` hold on to the non-`Sendable` `CXAction` and `CXProvider`
+it was handed; from a nonisolated method Swift 6 rejects the same capture with
+"passing closure as a 'sending' parameter risks causing data races". The name the
+system shows comes from `localizedName`; on current SDKs it is read from the
+bundle display name, and the old `init(localizedName:)` is deprecated.
 
-When a required VoIP call push arrives, report the incoming call to CallKit
-immediately. The system displays the native call UI. You must report required
-calls before the PushKit completion handler returns -- failure to do so causes
-the system to terminate your app.
+## Incoming call flow
+
+When a VoIP push says a call is ringing, report it to CallKit right away; the
+system then draws the native incoming-call UI. For a push that must be
+reported, the report has to happen before the PushKit completion handler runs,
+or the system kills the app.
 
 ```swift
-func reportIncomingCall(
-    uuid: UUID,
-    handle: String,
-    hasVideo: Bool
-) async throws {
-    let update = CXCallUpdate()
-    update.remoteHandle = CXHandle(type: .phoneNumber, value: handle)
-    update.hasVideo = hasVideo
-    update.localizedCallerName = "Jane Doe"
-
-    try await withCheckedThrowingContinuation {
-        (continuation: CheckedContinuation<Void, Error>) in
-        provider.reportNewIncomingCall(
-            with: uuid,
-            update: update
-        ) { error in
-            if let error {
-                continuation.resume(throwing: error)
-            } else {
-                continuation.resume()
+extension PhoneLine {
+    func announceIncoming(id: UUID, number: String, name: String, video: Bool) async throws {
+        let update = CXCallUpdate()
+        update.remoteHandle = CXHandle(type: .phoneNumber, value: number.trimmingCharacters(in: .whitespaces))
+        update.localizedCallerName = name
+        update.hasVideo = video
+
+        try await withCheckedThrowingContinuation { (cont: CheckedContinuation<Void, Error>) in
+            provider.reportNewIncomingCall(with: id, update: update) { error in
+                if let error { cont.resume(throwing: error) } else { cont.resume() }
             }
         }
     }
 }
 ```
 
-### Handling the Answer Action
+The report throws when Do Not Disturb or the user's block list filters the call.
+That is a normal outcome, not a crash path.
 
-Implement `CXProviderDelegate` to respond when the user answers:
+### Answering and ending
 
 ```swift
-extension CallManager: CXProviderDelegate {
-    func providerDidReset(_ provider: CXProvider) {
-        // End all calls, reset audio
+extension PhoneLine: @preconcurrency CXProviderDelegate {
+    func providerDidReset(_ cx: CXProvider) {
+        MediaSession.shared.hangUpEverything()
+        AudioRoute.tearDown()
     }
 
-    func provider(_ provider: CXProvider, perform action: CXAnswerCallAction) {
-        // Prepare audio, then fulfill only after the call is actually ready
-        configureAudioSession()
-        connectToCallServer(callUUID: action.callUUID) { success in
-            if success {
-                action.fulfill()
-            } else {
-                provider.reportCall(
-                    with: action.callUUID,
-                    endedAt: Date(),
-                    reason: .failed
-                )
-                action.fail()
+    func provider(_ cx: CXProvider, perform answer: CXAnswerCallAction) {
+        AudioRoute.prepareForCall()
+        Task {
+            do {
+                try await SignalingClient.shared.join(call: answer.callUUID)
+                answer.fulfill()
+            } catch {
+                cx.reportCall(with: answer.callUUID, endedAt: .now, reason: .failed)
+                answer.fail()
             }
         }
     }
 
-    func provider(_ provider: CXProvider, perform action: CXEndCallAction) {
-        disconnectFromCallServer(callUUID: action.callUUID)
-        action.fulfill()
+    func provider(_ cx: CXProvider, perform hangup: CXEndCallAction) {
+        Task {
+            await SignalingClient.shared.leave(call: hangup.callUUID)
+            hangup.fulfill()
+        }
     }
 }
 ```
 
-## Outgoing Call Flow
+`providerDidReset(_:)` means the system dropped every call: end all of them and
+reset audio. The answer action stays pending until the media server connection
+is up; only then is it fulfilled. If the connection fails, report the call as
+ended with `.failed` and fail the action.
+
+## Outgoing call flow
 
-Use `CXCallController` to request an outgoing call. The system routes the
-request through your `CXProviderDelegate`.
+Outgoing calls start with a request to `CXCallController`. The system checks it
+and hands it back through `provider(_:perform:)` with a `CXStartCallAction`.
 
 ```swift
-func startOutgoingCall(handle: String, hasVideo: Bool) {
-    let uuid = UUID()
-    let handle = CXHandle(type: .phoneNumber, value: handle)
-    let startAction = CXStartCallAction(call: uuid, handle: handle)
-    startAction.isVideo = hasVideo
-
-    let transaction = CXTransaction(action: startAction)
-    callController.request(transaction) { error in
-        if let error {
-            print("Failed to start call: \(error)")
+extension PhoneLine {
+    func dial(_ address: String, video: Bool) -> UUID {
+        let id = UUID()
+        let start = CXStartCallAction(call: id, handle: CXHandle(type: .phoneNumber, value: address))
+        start.isVideo = video
+        controller.request(CXTransaction(action: start)) { error in
+            if let error { Log.calls.error("dial refused: \(error)") }
         }
+        return id
     }
-}
-```
 
-### Delegate Methods for Outgoing Calls
-
-```swift
-extension CallManager {
-    func provider(_ provider: CXProvider, perform action: CXStartCallAction) {
-        configureAudioSession()
-        // Begin connecting to server
-        provider.reportOutgoingCall(
-            with: action.callUUID,
-            startedConnectingAt: Date()
-        )
-
-        connectToServer(callUUID: action.callUUID) {
-            provider.reportOutgoingCall(
-                with: action.callUUID,
-                connectedAt: Date()
-            )
+    func provider(_ cx: CXProvider, perform dial: CXStartCallAction) {
+        AudioRoute.prepareForCall()
+        let id = dial.callUUID
+        cx.reportOutgoingCall(with: id, startedConnectingAt: .now)
+        Task {
+            do {
+                try await SignalingClient.shared.place(call: id, to: dial.handle.value)
+                cx.reportOutgoingCall(with: id, connectedAt: .now)
+                dial.fulfill()
+            } catch {
+                dial.fail()
+            }
         }
-        action.fulfill()
     }
 }
 ```
 
-## PushKit VoIP Registration
+Report both `startedConnectingAt` and `connectedAt`; Recents and the call timer
+use them.
+
+## PushKit VoIP registration
+
+Create the registry on every launch, not lazily, and forward each token change
+to your server.
+
+Report rules:
 
-Register for VoIP pushes at every app launch and send token changes to your
-server. For iOS 13 SDK+ apps, every report-required VoIP call push must be
-reported before PushKit completion using CallKit, or LiveCommunicationKit for
-apps built on that framework. On iOS 26.4+, `PKVoIPPushMetadata.mustReport` is
-the gate: `true` means report before completion; `false` means no CallKit or
-LiveCommunicationKit report is required. Missing a required report before
-completion can terminate the app, and repeated failures may stop VoIP delivery.
+- Linked against SDK 13 or newer: every VoIP push that is a call must be
+  reported to CallKit (LiveCommunicationKit apps report there instead)
+  before the PushKit completion handler is called.
+- iOS 26.4 and later: `PKVoIPPushMetadata.mustReport` decides. When it is `true`,
+  the report precedes completion; when `false`, that push can be handled
+  without any report at all.
+- A skipped required report may end the process; keep skipping and the
+  system may stop delivering VoIP pushes altogether.
 
-| Path | Report decision | Completion timing |
-|---|---|---|
-| iOS 26.4+ `mustReport == true` | Report with CallKit or LiveCommunicationKit | After report callback |
-| iOS 26.4+ `mustReport == false` | No CallKit/LiveCommunicationKit report required | After local handling |
-| Older delegate | iOS 13 SDK+ treats VoIP call pushes as report-required | After report callback |
+| Delivery path | Report? | When to call completion |
+| --- | --- | --- |
+| 26.4+ delegate, `mustReport == true` | Yes | After the report callback |
+| 26.4+ delegate, `mustReport == false` | No | After local handling |
+| Older delegate | Treat every VoIP call push as required | After the report callback |
 
 ```swift
 import PushKit
 
-final class PushManager: NSObject, PKPushRegistryDelegate {
-    let registry: PKPushRegistry
+@MainActor
+final class VoIPInbox: NSObject, @preconcurrency PKPushRegistryDelegate {
+    private let registry = PKPushRegistry(queue: .main)
 
-    override init() {
-        registry = PKPushRegistry(queue: .main)
-        super.init()
+    func start() {
         registry.delegate = self
         registry.desiredPushTypes = [.voIP]
     }
 
-    func pushRegistry(
-        _ registry: PKPushRegistry,
-        didUpdate pushCredentials: PKPushCredentials,
-        for type: PKPushType
-    ) {
-        let token = pushCredentials.token
-            .map { String(format: "%02x", $0) }
-            .joined()
-        // Send token to your server
-        sendTokenToServer(token)
+    func pushRegistry(_ reg: PKPushRegistry, didUpdate credentials: PKPushCredentials, for type: PKPushType) {
+        let hex = credentials.token.reduce(into: "") { out, byte in out += String(format: "%02x", byte) }
+        Backend.shared.upload(voipToken: hex)
     }
 
     @available(iOS 26.4, *)
-    func pushRegistry(
-        _ registry: PKPushRegistry,
-        didReceiveIncomingVoIPPushWith payload: PKPushPayload,
-        metadata: PKVoIPPushMetadata,
-        withCompletionHandler completion: @escaping @Sendable () -> Void
-    ) {
+    func pushRegistry(_ reg: PKPushRegistry,
+                      didReceiveIncomingVoIPPushWith payload: PKPushPayload,
+                      metadata: PKVoIPPushMetadata,
+                      withCompletionHandler completion: @escaping @Sendable () -> Void) {
         guard metadata.mustReport else {
             completion()
             return
         }
-        handleIncomingVoIPPush(payload, completion: completion)
+        ring(from: payload, then: completion)
     }
 
-    // Keep the older callback for iOS 26.0-26.3 and older deployment targets.
-    func pushRegistry(
-        _ registry: PKPushRegistry,
-        didReceiveIncomingPushWith payload: PKPushPayload,
-        for type: PKPushType,
-        completion: @escaping () -> Void
-    ) {
+    func pushRegistry(_ reg: PKPushRegistry,
+                      didReceiveIncomingPushWith payload: PKPushPayload,
+                      for type: PKPushType,
+                      completion: @escaping () -> Void) {
         guard type == .voIP else {
             completion()
             return
         }
-
-        handleIncomingVoIPPush(payload, completion: completion)
+        ring(from: payload, then: completion)
     }
 
-    private func handleIncomingVoIPPush(
-        _ payload: PKPushPayload,
-        completion: @escaping () -> Void
-    ) {
-        let callUUID = UUID()
-        let handle = payload.dictionaryPayload["handle"] as? String ?? "Unknown"
-
+    private func ring(from payload: PKPushPayload, then completion: @escaping () -> Void) {
+        let body = payload.dictionaryPayload
+        let number = body["from"] as? String ?? "Unknown"
+        let name = body["display"] as? String ?? number
+        let video = body["video"] as? Bool ?? false
         Task {
             do {
-                try await CallManager.shared.reportIncomingCall(
-                    uuid: callUUID,
-                    handle: handle,
-                    hasVideo: false
-                )
+                try await PhoneLine.shared.announceIncoming(id: UUID(), number: number, name: name, video: video)
             } catch {
-                // Call was filtered by DND or block list
+                Log.calls.notice("call filtered or rejected: \(error)")
             }
             completion()
         }
@@ -283,218 +253,167 @@ final class PushManager: NSObject, PKPushRegistryDelegate {
 }
 ```
 
-Server-side VoIP pushes should use a short lifetime: set `apns-expiration` to
-`0` or only a few seconds. After the initial push wakes the app, send hangups
-and call-detail changes over the app-server connection instead of sending more
-VoIP pushes.
+Keep the older delegate method for iOS 26.0 through 26.3 and for lower
+deployment targets. The registry delivers on `.main`, which is why the inbox is
+`@MainActor`: the `Task` in `ring` can then carry the non-`Sendable` completion
+handler without leaving the actor. Completion runs after the report attempt on both the
+success and the error path.
 
-## Audio Session Coordination
+Server side: send VoIP pushes with `apns-expiration: 0` or a few seconds; a
+ring that arrives a minute late is worse than none. After the first push has
+woken the app, hangups and changed call details travel over your own socket or
+API channel instead of further VoIP pushes.
 
-CallKit manages audio session activation/deactivation. Configure your audio
-session when CallKit tells you to, not before.
-Review answers should name both sides: start media only in
-`provider(_:didActivate:)`, and stop/tear down media in
-`provider(_:didDeactivate:)` or reset paths.
+## Audio session coordination
 
-```swift
-extension CallManager {
-    func provider(_ provider: CXProvider, didActivate audioSession: AVAudioSession) {
-        // Audio session is now active -- start audio engine / WebRTC
-        startAudioEngine()
-    }
+CallKit owns activation and deactivation of the audio session. Set the category
+while preparing the call, and wait for CallKit before touching media.
 
-    func provider(_ provider: CXProvider, didDeactivate audioSession: AVAudioSession) {
-        // Audio session deactivated -- stop audio engine
-        stopAudioEngine()
-    }
+```swift
+import AVFAudio
 
-    func configureAudioSession() {
-        let session = AVAudioSession.sharedInstance()
+enum AudioRoute {
+    static func prepareForCall() {
         do {
-            try session.setCategory(
-                .playAndRecord,
-                mode: .voiceChat,
-                options: [.allowBluetooth, .allowBluetoothA2DP]
-            )
+            try AVAudioSession.sharedInstance().setCategory(.playAndRecord, mode: .voiceChat,
+                                    options: [.allowBluetoothHFP, .allowBluetoothA2DP])
         } catch {
-            print("Audio session configuration failed: \(error)")
+            Log.calls.error("audio category failed: \(error)")
         }
     }
-}
-```
-
-## Call Directory Extension and Manager
 
-Use Call Directory for preloaded caller ID/blocking, not per-call API lookup.
-The extension loads sorted bulk data in `beginRequest(with:)`; the main app uses
-`CXCallDirectoryManager` to check enabled status, open Call Blocking &
-Identification settings when disabled, and reload after data changes. Store
-`CXCallDirectoryPhoneNumber` as country code plus digits in ascending order
-(for example `18005551234`), not a formatted string.
-
-```swift
-import CallKit
+    static func tearDown() { MediaSession.shared.stopEngine() }
+}
 
-final class CallDirectoryHandler: CXCallDirectoryProvider {
-    override func beginRequest(
-        with context: CXCallDirectoryExtensionContext
-    ) {
-        if context.isIncremental {
-            addOrRemoveIncrementalEntries(to: context)
-        } else {
-            addAllEntries(to: context)
-        }
-        context.completeRequest()
+extension PhoneLine {
+    func provider(_ cx: CXProvider, didActivate session: AVAudioSession) {
+        MediaSession.shared.startEngine()
     }
 
-    private func addAllEntries(
-        to context: CXCallDirectoryExtensionContext
-    ) {
-        // Country code + digits, sorted in ascending order
-        let blockedNumbers: [CXCallDirectoryPhoneNumber] = [
-            18005551234, 18005555678
-        ]
-        for number in blockedNumbers {
-            context.addBlockingEntry(
-                withNextSequentialPhoneNumber: number
-            )
-        }
-
-        let identifiedNumbers: [(CXCallDirectoryPhoneNumber, String)] = [
-            (18005551111, "Local Pizza"),
-            (18005552222, "Dentist Office")
-        ]
-        for (number, label) in identifiedNumbers {
-            context.addIdentificationEntry(
-                withNextSequentialPhoneNumber: number,
-                label: label
-            )
-        }
+    func provider(_ cx: CXProvider, didDeactivate session: AVAudioSession) {
+        MediaSession.shared.stopEngine()
     }
 }
 ```
 
-### Main-App Manager: Status, Settings, Reload
+Media starts in `provider(_:didActivate:)` and stops in
+`provider(_:didDeactivate:)` or a reset path. A review should point at both
+callbacks by name.
+
+## Call Directory extension and manager
+
+A Call Directory supplies caller ID labels and blocked numbers that are loaded
+in advance. It cannot look anything up while a call is ringing.
 
 ```swift
-let manager = CXCallDirectoryManager.sharedInstance
-manager.getEnabledStatusForExtension(withIdentifier: extensionID) { status, _ in
-    guard status == .enabled else {
-        manager.openSettings { _ in } // Call Blocking & Identification
-        return
+import CallKit
+
+final class SpamListProvider: CXCallDirectoryProvider {
+    override func beginRequest(with ctx: CXCallDirectoryExtensionContext) {
+        if ctx.isIncremental {
+            applyChanges(to: ctx)
+        } else {
+            for number in SharedStore.blocked().sorted() {
+                ctx.addBlockingEntry(withNextSequentialPhoneNumber: number)
+            }
+            for entry in SharedStore.labels().sorted(by: { $0.key < $1.key }) {
+                ctx.addIdentificationEntry(withNextSequentialPhoneNumber: entry.key, label: entry.value)
+            }
+        }
+        ctx.completeRequest()
     }
-    manager.reloadExtension(withIdentifier: extensionID) { _ in }
 }
 ```
 
-Check `getEnabledStatusForExtension(...)` before assuming the extension is
-active, use `openSettings(...)` for Call Blocking & Identification when
-disabled, and call `reloadExtension(...)` after data changes. Route APNs
-auth-key rotation and normal remote-notification setup to push-notifications.
-
-## Common Mistakes
-
-### DON'T: Fail to report a required call on VoIP push receipt
-
-Follow the PushKit report rules above: iOS 13 SDK+ apps must report
-report-required VoIP call pushes before completion, and on iOS 26.4+
-`PKVoIPPushMetadata.mustReport` identifies which pushes are required. Missing a
-required report can terminate the app; repeated failures may stop VoIP delivery.
-
-Do not treat a required VoIP push as a data-only notification. Report the call
-to CallKit and call the PushKit completion handler from the report completion.
-
-### DON'T: Fulfill answer before the call is connected
-
-When the user answers before your app has established the server/media
-connection, leave the `CXAnswerCallAction` pending while connecting. Fulfill it
-after the call is ready; if connection fails, fail the action and report the
-call ended with `.failed`.
-
-### DON'T: Start audio before CallKit activates the session
-
-Starting your audio engine before `provider(_:didActivate:)` causes silence
-or immediate deactivation. CallKit manages session priority with the system.
-
-Prepare audio in the answer/start action if needed, then start media only from
-`provider(_:didActivate:)`.
-
-For iOS 26 call translation, set `CXProviderConfiguration.supportsAudioTranslation`
-when your service supports it and handle `CXSetTranslatingCallAction`. If a
-person mutes during a translated call, mute app input with
-`CXSetMutedCallAction`; do not deactivate upstream audio that translated audio
-depends on.
-
-For encrypted VoIP metadata, use `CXProvider.reportNewIncomingVoIPPushPayload`
-only from a notification service extension when the server cannot determine
-whether encrypted content is a VoIP call or other data. That path requires the
-`com.apple.developer.usernotifications.filtering` entitlement; otherwise send a
-normal PushKit VoIP push.
-
-### DON'T: Forget to call action.fulfill() or action.fail()
-
-Failing to fulfill or fail an action leaves the call in a limbo state and
-triggers the timeout handler.
-
-Every provider action path must eventually call `fulfill()` or `fail()`,
-including network-error and cancellation paths.
-
-### DON'T: Ignore push token refresh
-
-The VoIP push token can change at any time. If your server has a stale token,
-pushes silently fail and incoming calls never arrive.
-
-Send the token to your server every time `didUpdate pushCredentials` fires,
-not just during first-run onboarding.
-
-### DON'T: Use Call Directory for per-call lookup
-
-Call Directory extensions provide preloaded caller ID and blocking data. They
-cannot ask a web service for the incoming caller during call presentation.
-Fetch or generate the dataset ahead of time, reload the extension, and add
-entries in sorted sequential order.
-
-## Review Checklist
-
-- [ ] VoIP background mode enabled in capabilities
-- [ ] Single `CXProvider` instance created at app launch and retained
-- [ ] `CXProviderDelegate` set before reporting any calls
-- [ ] iOS 26.4+ PushKit path reports when `mustReport` is true and may skip when false
-- [ ] iOS 13 SDK+ PushKit VoIP call pushes report to CallKit before completion
-- [ ] VoIP APNs requests use `apns-expiration` of `0` or only a few seconds
-- [ ] Hangups and detail updates use the app-server connection after the initial push
-- [ ] `action.fulfill()` or `action.fail()` called for every provider delegate action
-- [ ] `CXAnswerCallAction` fulfilled only after the call server/media connection is ready
-- [ ] Audio engine started only after `provider(_:didActivate:)` callback
-- [ ] Audio engine stopped in `provider(_:didDeactivate:)` callback
-- [ ] Audio session category set to `.playAndRecord` with `.voiceChat` mode
-- [ ] VoIP push token sent to server on every `didUpdate pushCredentials` callback
-- [ ] `PKPushRegistry` created at every app launch (not lazily)
-- [ ] Call Directory data is preloaded, not fetched per incoming call
-- [ ] `CXCallDirectoryPhoneNumber` documented as country calling code + digits
-- [ ] `CXCallDirectoryManager` names status check, reload, and settings-opening APIs
-- [ ] `CXCallUpdate` populated with `localizedCallerName` and `remoteHandle`
-- [ ] Outgoing calls report `startedConnectingAt` and `connectedAt` timestamps
-- [ ] iOS 26 call translation keeps upstream audio active during mute
-- [ ] Encrypted metadata filtering mentions the notification service extension entitlement
+A `CXCallDirectoryPhoneNumber` is an `Int64`: country calling code followed by
+the national digits, for example `14155550123`, never a formatted string.
+Entries go in ascending order.
+
+In the containing app, use `CXCallDirectoryManager.sharedInstance`:
+
+- `getEnabledStatusForExtension(withIdentifier:)` before assuming the extension
+  is on.
+- When the status is not `.enabled`, `openSettings { _ in }` takes the user to
+  Call Blocking & Identification.
+- After the dataset changes, `reloadExtension(withIdentifier:)`.
+
+Rotating APNs keys and the usual notification registration are covered by
+`push-notifications`.
+
+## Common mistakes
+
+- **Treating a call push as data.** A required VoIP call push that is not
+  reported ends the process. Hand it to CallKit first and let the report's
+  callback be where PushKit's completion runs.
+- **Fulfilling the answer too early.** Keep `CXAnswerCallAction` pending while
+  connecting; fulfill once media is ready; on failure, fail it and report the
+  call ended with `.failed`.
+- **Starting audio before activation.** Media started before
+  `provider(_:didActivate:)` plays silence or gets deactivated at once, because
+  CallKit arbitrates session priority. Prepare in the answer or start action,
+  play only after activation.
+- **Missing iOS 26 call translation.** Set
+  `CXProviderConfiguration.supportsAudioTranslation` when the app supports it
+  and handle `CXSetTranslatingCallAction`.
+- **Muting by killing audio.** During a translated call, mute the app's own
+  input in `CXSetMutedCallAction`; do not deactivate the upstream audio that
+  translation reads.
+- **Overusing encrypted payload reporting.** `CXProvider.reportNewIncomingVoIPPushPayload`
+  belongs in a notification service extension, and only when the server cannot
+  tell whether encrypted content is a call. If it can tell, send a normal
+  PushKit VoIP push. The extension needs the
+  entitlement `com.apple.developer.usernotifications.filtering`.
+- **Leaving an action unresolved.** A call action that is neither fulfilled nor
+  failed hangs until its timeout fires. Every branch, including network errors
+  and cancellation, ends with `fulfill()` or `fail()`.
+- **Caching the push token.** It can change at any moment; a stale server copy
+  makes pushes vanish silently. Upload on every `didUpdate` credentials call.
+- **Per-call lookup in Call Directory.** The extension cannot call a web service
+  when a call is presented. Fetch ahead, reload, and add sorted sequential
+  entries.
+
+## Review checklist
+
+- [ ] Voice over IP background mode is on
+- [ ] Exactly one `CXProvider`, created at launch and retained
+- [ ] Provider delegate is set before any call is reported
+- [ ] On 26.4+, a `mustReport` of true triggers a report; false allows skipping it
+- [ ] With SDK 13 or newer, each VoIP call push is reported ahead of completion
+- [ ] `apns-expiration` is 0 or a few seconds
+- [ ] After the waking push, hangups and call details use the app's own server channel
+- [ ] Every delegate action ends in `fulfill()` or `fail()`
+- [ ] Answer is fulfilled only when the server and media connection are ready
+- [ ] Audio engine starts after `didActivate` and stops in `didDeactivate`
+- [ ] Audio category is `.playAndRecord` with mode `.voiceChat`
+- [ ] Token uploaded on every `didUpdate` credentials callback
+- [ ] `PKPushRegistry` created on every launch, not lazily
+- [ ] Call Directory data is preloaded, never fetched per call
+- [ ] `CXCallDirectoryPhoneNumber` described as country calling code plus digits
+- [ ] `CXCallDirectoryManager` status check, reload and settings APIs are named
+- [ ] `CXCallUpdate` sets `localizedCallerName` and `remoteHandle`
+- [ ] Dialed calls send both `startedConnectingAt` and `connectedAt` timestamps
+- [ ] Translated calls keep upstream audio live while muted
+- [ ] Encrypted payload filtering lists the filtering entitlement the extension needs
 
 ## References
 
-- Extended patterns (hold, mute, group calls, delegate lifecycle): [references/callkit-patterns.md](references/callkit-patterns.md)
-- [CallKit framework](https://sosumi.ai/documentation/callkit)
-- [CXProvider](https://sosumi.ai/documentation/callkit/cxprovider)
-- [CXCallController](https://sosumi.ai/documentation/callkit/cxcallcontroller)
-- [CXCallAction](https://sosumi.ai/documentation/callkit/cxcallaction)
-- [CXCallUpdate](https://sosumi.ai/documentation/callkit/cxcallupdate)
-- [CXProviderConfiguration](https://sosumi.ai/documentation/callkit/cxproviderconfiguration)
-- [CXProviderDelegate](https://sosumi.ai/documentation/callkit/cxproviderdelegate)
-- [PKPushRegistry](https://sosumi.ai/documentation/pushkit/pkpushregistry)
-- [PKPushRegistryDelegate](https://sosumi.ai/documentation/pushkit/pkpushregistrydelegate)
-- [PKVoIPPushMetadata](https://sosumi.ai/documentation/pushkit/pkvoippushmetadata)
-- [CXCallDirectoryProvider](https://sosumi.ai/documentation/callkit/cxcalldirectoryprovider)
-- [CXCallDirectoryPhoneNumber](https://sosumi.ai/documentation/callkit/cxcalldirectoryphonenumber)
-- [CXCallDirectoryManager](https://sosumi.ai/documentation/callkit/cxcalldirectorymanager)
-- [CXSetTranslatingCallAction](https://sosumi.ai/documentation/callkit/cxsettranslatingcallaction)
-- [reportNewIncomingVoIPPushPayload(_:completion:)](https://sosumi.ai/documentation/callkit/cxprovider/reportnewincomingvoippushpayload(_:completion:))
-- [Making and receiving VoIP calls](https://sosumi.ai/documentation/callkit/making-and-receiving-voip-calls)
-- [Responding to VoIP Notifications from PushKit](https://sosumi.ai/documentation/pushkit/responding-to-voip-notifications-from-pushkit)
+- [Longer patterns](references/callkit-patterns.md): observable manager, hold
+  and mute, concurrent calls, call observer, encrypted filtering, incremental
+  Call Directory, local testing
+- [CallKit](https://developer.apple.com/documentation/callkit)
+- [CXProvider](https://developer.apple.com/documentation/callkit/cxprovider)
+- [CXCallController](https://developer.apple.com/documentation/callkit/cxcallcontroller)
+- [CXCallAction](https://developer.apple.com/documentation/callkit/cxcallaction)
+- [CXCallUpdate](https://developer.apple.com/documentation/callkit/cxcallupdate)
+- [CXProviderConfiguration](https://developer.apple.com/documentation/callkit/cxproviderconfiguration)
+- [CXProviderDelegate](https://developer.apple.com/documentation/callkit/cxproviderdelegate)
+- [CXSetTranslatingCallAction](https://developer.apple.com/documentation/callkit/cxsettranslatingcallaction)
+- [reportNewIncomingVoIPPushPayload(_:completion:)](https://developer.apple.com/documentation/callkit/cxprovider/reportnewincomingvoippushpayload(_:completion:))
+- [CXCallDirectoryProvider](https://developer.apple.com/documentation/callkit/cxcalldirectoryprovider)
+- [CXCallDirectoryPhoneNumber](https://developer.apple.com/documentation/callkit/cxcalldirectoryphonenumber)
+- [CXCallDirectoryManager](https://developer.apple.com/documentation/callkit/cxcalldirectorymanager)
+- [PKPushRegistry](https://developer.apple.com/documentation/pushkit/pkpushregistry)
+- [PKPushRegistryDelegate](https://developer.apple.com/documentation/pushkit/pkpushregistrydelegate)
+- [PKVoIPPushMetadata](https://developer.apple.com/documentation/pushkit/pkvoippushmetadata)
+- Article: [VoIP call handling with CallKit](https://developer.apple.com/documentation/callkit/making-and-receiving-voip-calls)
+- Article: [PushKit VoIP notification handling](https://developer.apple.com/documentation/pushkit/responding-to-voip-notifications-from-pushkit)