@npaw/forge-react-native 9.6.1

package/ios/ForgeApple/Sources/NPAWForgeCapture/ForgeAutomaticCapture.swift

@@ -0,0 +1,639 @@
+/**
+ * Copyright (C) NPAW - All Rights Reserved
+ *
+ * This source code is protected under international copyright law. All rights
+ * reserved and protected by the copyright holders.
+ * This file is confidential and only available to authorized individuals with the
+ * permission of the copyright holders. If you encounter this file and do not have
+ * permission, please contact the copyright holders and delete this file.
+ *
+ *
+ * @author: Victor Soto <victor.soto@nicepeopleatwork.com>
+ * @description: Install-gated Apple automatic capture for lifecycle, screens, interactions, and crash retry.
+ */
+
+import Foundation
+#if canImport(NPAWForgeCore)
+import NPAWForgeCore
+#endif
+#if canImport(UIKit)
+import UIKit
+#endif
+
+public struct CaptureConfiguration: Equatable {
+    public var enabled: Bool
+    public var navigationEnabled: Bool
+    public var clickEnabled: Bool
+    public var lifecycleEnabled: Bool
+    public var crashEnabled: Bool
+    public var consentGranted: Bool
+    public var maxStringLength: Int
+    public var maxPayloadFields: Int
+
+    public init(
+        enabled: Bool = true,
+        navigationEnabled: Bool = true,
+        clickEnabled: Bool = true,
+        lifecycleEnabled: Bool = true,
+        crashEnabled: Bool = true,
+        consentGranted: Bool = true,
+        maxStringLength: Int = 512,
+        maxPayloadFields: Int = 64
+    ) {
+        self.enabled = enabled
+        self.navigationEnabled = navigationEnabled
+        self.clickEnabled = clickEnabled
+        self.lifecycleEnabled = lifecycleEnabled
+        self.crashEnabled = crashEnabled
+        self.consentGranted = consentGranted
+        self.maxStringLength = max(1, maxStringLength)
+        self.maxPayloadFields = max(1, maxPayloadFields)
+    }
+}
+
+public enum RawEventName {
+    public static let screenView = "raw_screen_view"
+    public static let fragmentView = "raw_fragment_view"
+    public static let composeView = "raw_compose_view"
+    public static let pageView = "raw_page_view"
+    public static let deepLinkReceived = "raw_deep_link_received"
+    public static let tap = "raw_tap"
+    public static let click = "raw_click"
+    public static let scroll = "raw_scroll"
+    public static let swipe = "raw_swipe"
+    public static let focusChange = "raw_focus_change"
+    public static let focusDwell = "raw_focus_dwell"
+    public static let remoteKey = "raw_remote_key"
+    public static let select = "raw_select"
+    public static let sectionVisible = "raw_section_visible"
+    public static let sectionHidden = "raw_section_hidden"
+    public static let contentImpression = "raw_content_impression"
+    public static let contentDwell = "raw_content_dwell"
+    public static let attribution = "raw_attribution"
+    public static let applicationForeground = "raw_application_foreground"
+    public static let applicationBackground = "raw_application_background"
+
+    public static func normalize(_ value: String) -> String {
+        switch value {
+        case "screen", "screen_view", "screenView": return screenView
+        case "fragment", "fragment_view", "fragmentView": return fragmentView
+        case "compose", "compose_view", "composeView": return composeView
+        case "deep_link", "deepLink": return deepLinkReceived
+        case "tap": return tap
+        case "click", "button_click": return click
+        case "scroll": return scroll
+        case "swipe": return swipe
+        case "foreground": return applicationForeground
+        case "background": return applicationBackground
+        default: return value.hasPrefix("raw_") ? value : "raw_\(value)"
+        }
+    }
+}
+
+public struct ScreenContext: Equatable {
+    public var current: String?
+    public var previous: String?
+
+    public init(current: String?, previous: String? = nil) {
+        self.current = current
+        self.previous = previous
+    }
+}
+
+public enum ForegroundState: String {
+    case foreground
+    case background
+    case unknown
+}
+
+public final class RawEventCapture {
+    private let kernel: ForgeApple
+    private let configuration: CaptureConfiguration
+    private let clientId: String
+    /// Single family chokepoint combining the local configuration flags with
+    /// the kernel capture-plan bits; local-flags-only before the first plan.
+    private let gate: CapturePlanGate
+    private var recentKeys: [String] = []
+    private let maxRecentKeys = 128
+    private var currentScreen: ScreenContext?
+    private let lock = NSRecursiveLock()
+
+    public init(kernel: ForgeApple, configuration: CaptureConfiguration, clientId: String) {
+        self.kernel = kernel
+        self.configuration = configuration
+        self.clientId = clientId
+        self.gate = CapturePlanGate(configuration: configuration)
+    }
+
+    /// Applies a kernel capture plan to the family gate. Safe to call from
+    /// the runtime callback thread; the gate flips immediately while observer
+    /// reconciliation hops to the main thread separately.
+    public func applyPlan(_ plan: ForgeCapturePlan) {
+        gate.apply(plan)
+    }
+
+    /// Current effective feature snapshot (local flags AND plan bits).
+    public var effectiveFeatures: EffectiveCaptureFeatures {
+        gate.features
+    }
+
+    /// Latest applied kernel capture plan, or `nil` before the first plan.
+    public var capturePlan: ForgeCapturePlan? {
+        gate.plan
+    }
+
+    @discardableResult
+    public func capture(
+        eventName: String,
+        data: [String: String] = [:],
+        screen: ScreenContext? = nil,
+        foregroundState: ForegroundState = .unknown,
+        timestampMs: Int64 = ForgeClock.nowMs(),
+        urgent: Bool = false
+    ) -> ForgeOutcome {
+        lock.lock()
+        defer { lock.unlock() }
+        guard configuration.enabled, configuration.consentGranted else { return .ignoredInvalidState }
+        let normalized = RawEventName.normalize(eventName)
+        guard isFamilyEnabled(normalized) else { return .ignoredInvalidState }
+        let resolvedScreen = screen ?? currentScreen
+        if let current = screen?.current, !current.isEmpty {
+            currentScreen = screen
+        }
+        let key = dedupeKey(eventName: normalized, screen: resolvedScreen, data: data, timestampMs: timestampMs)
+        guard !recentKeys.contains(key) else { return .ignoredDuplicate }
+        recentKeys.append(key)
+        if recentKeys.count > maxRecentKeys {
+            recentKeys.removeFirst(recentKeys.count - maxRecentKeys)
+        }
+
+        let bounded = PrivacySanitizer.sanitize(data, maxValueLength: configuration.maxStringLength)
+            .prefix(configuration.maxPayloadFields)
+            .reduce(into: [String: String]()) { output, element in output[element.key] = element.value }
+
+        if normalized == RawEventName.applicationForeground {
+            _ = kernel.recordApplicationForeground(true, timestampMs: timestampMs)
+        } else if normalized == RawEventName.applicationBackground {
+            _ = kernel.recordApplicationForeground(false, timestampMs: timestampMs)
+        }
+
+        return kernel.recordEvent(
+            eventName: normalized,
+            payload: flatten(
+                eventName: normalized,
+                data: bounded,
+                screen: resolvedScreen,
+                foregroundState: foregroundState
+            ),
+            timestampMs: timestampMs,
+            urgent: urgent
+        )
+    }
+
+    public func setCurrentScreen(_ screen: ScreenContext?) {
+        lock.lock()
+        currentScreen = screen
+        lock.unlock()
+    }
+
+    /// Name of the screen currently attached to captured events, if any.
+    public var currentScreenName: String? {
+        lock.lock()
+        defer { lock.unlock() }
+        return currentScreen?.current
+    }
+
+    private func isFamilyEnabled(_ eventName: String) -> Bool {
+        gate.isEventFamilyEnabled(eventName)
+    }
+
+    private func dedupeKey(eventName: String, screen: ScreenContext?, data: [String: String], timestampMs: Int64) -> String {
+        let interaction = data["interactionKey"] ?? data["elementId"].map { "\(data["elementType"] ?? "view"):\($0)" }
+        return "\(eventName):\(screen?.current ?? ""):\(interaction ?? String(data.hashValue)):\(timestampMs / 500)"
+    }
+
+    private func flatten(
+        eventName: String,
+        data: [String: String],
+        screen: ScreenContext?,
+        foregroundState: ForegroundState
+    ) -> [String: String] {
+        var output: [String: String] = [
+            "eventId": UUID().uuidString,
+            "clientId": clientId,
+            "foregroundState": foregroundState.rawValue,
+        ]
+        if let current = screen?.current { output["screenName"] = current }
+        if let previous = screen?.previous { output["previousScreenName"] = previous }
+        data.forEach { output["data.\($0.key)"] = $0.value }
+        return output
+    }
+}
+
+public enum ForgeAutomaticCapture {
+    private static let lock = NSLock()
+    /// Weak-keyed registry (mirrors Android's `WeakHashMap<NPAWForge, AutomaticCaptureHandle>`):
+    /// entries disappear with their forge, so rebuilt SDK instances never alias a
+    /// stale handle and dead kernels are not retained forever.
+    private static let handles = NSMapTable<NPAWForge, AutomaticCaptureHandle>.weakToStrongObjects()
+
+    public static func install(
+        forge: NPAWForge,
+        configuration: CaptureConfiguration = CaptureConfiguration()
+    ) -> AutomaticCaptureHandle {
+        lock.lock()
+        defer { lock.unlock() }
+        if let existing = handles.object(forKey: forge) { return existing }
+        let handle = AutomaticCaptureHandle(forge: forge, configuration: configuration)
+        handles.setObject(handle, forKey: forge)
+        handle.install()
+        return handle
+    }
+
+    /// Uninstalls and removes the handle registered for `forge`, if any.
+    public static func uninstall(forge: NPAWForge) {
+        lock.lock()
+        let handle = handles.object(forKey: forge)
+        handles.removeObject(forKey: forge)
+        lock.unlock()
+        handle?.uninstall()
+    }
+
+    static func removeHandle(forge: NPAWForge) {
+        lock.lock()
+        handles.removeObject(forKey: forge)
+        lock.unlock()
+    }
+
+    public static func registerAutoInstall() {
+        ForgeAutomaticCaptureRegistry.register { forge in
+            _ = install(forge: forge)
+        }
+    }
+}
+
+public final class AutomaticCaptureHandle {
+    public let capture: RawEventCapture
+    /// F3 sections engine owner: installed/uninstalled by plan reconciliation,
+    /// flushed on screen changes, and consulted for interaction enrichment.
+    /// Emits through the regular raw-event capture chokepoint.
+    let sectionsCoordinator: ForgeSectionsCoordinator
+    private weak var forge: NPAWForge?
+    private let configuration: CaptureConfiguration
+    /// Guards `observers` and `lifecycleObserversInstalled`: install/uninstall
+    /// run on the integrator's thread while plan reconciliation runs on main.
+    private let observerStateLock = NSRecursiveLock()
+    private var observers: [NSObjectProtocol] = []
+    private var lifecycleObserversInstalled = false
+    private var crashStore: CrashRecordStore?
+    private var crashSubscription: ForgeEventSubscription?
+    private var planSubscription: ForgeEventSubscription?
+    /// Guards the single deep-link retention slot: `deepLink` can arrive on
+    /// any thread while plan reconciliation replays on main.
+    private let retainedDeepLinkLock = NSLock()
+    /// Single retention slot (Android `DeepLinkCapture` parity): the most
+    /// recent deep link observed while attribution derivation was ineffective
+    /// (fail-closed pre-plan, or the plan keeps the family/knob off) — the
+    /// iOS cold-start campaign landing case. Plan reconciliation replays
+    /// exactly this URL once derivation turns effective; the per-URL dedupe
+    /// keeps the replay idempotent because it only records accepted
+    /// derivations.
+    private var retainedDeepLinkWhileIneffective: URL?
+
+    init(forge: NPAWForge, configuration: CaptureConfiguration) {
+        self.forge = forge
+        self.configuration = configuration
+        let capture = RawEventCapture(
+            kernel: forge.kernel,
+            configuration: configuration,
+            clientId: "apple-\(Bundle.main.bundleIdentifier ?? "unknown")"
+        )
+        self.capture = capture
+        // The coordinator only holds the capture chokepoint (never the
+        // handle), so the emit closure cannot create a retain cycle.
+        self.sectionsCoordinator = ForgeSectionsCoordinator(emit: { kind, params in
+            _ = capture.capture(eventName: kind, data: params, foregroundState: .foreground)
+        })
+    }
+
+    public func install() {
+        // Pre-first-plan behavior is identical to the plan-less pipeline:
+        // lifecycle observers install unconditionally and family gating
+        // happens at capture time from the local flags.
+        installLifecycleCapture()
+        if configuration.crashEnabled {
+            installCrashCapture()
+        }
+        // Closure capture is weak, so the kernel listener list never pins the
+        // handle (mirrors the Android WeakReference subscription contract).
+        planSubscription = forge?.addCapturePlanListener { [weak self] plan in
+            self?.applyPlan(plan)
+        }
+    }
+
+    public func uninstall() {
+        planSubscription?.cancel()
+        planSubscription = nil
+        removeLifecycleObservers()
+        // Sections teardown removes KVO tokens, the safety timer, and
+        // notification observers; the sampler is main-thread affine.
+        let coordinator = sectionsCoordinator
+        runOnMain { coordinator.shutdown() }
+        crashSubscription?.cancel()
+        crashSubscription = nil
+        if let forge {
+            ForgeAutomaticCapture.removeHandle(forge: forge)
+        }
+    }
+
+    deinit {
+        planSubscription?.cancel()
+        observers.forEach(NotificationCenter.default.removeObserver)
+        crashSubscription?.cancel()
+    }
+
+    /// Applies a kernel capture plan: the family gate flips immediately on
+    /// the calling (runtime callback) thread so newly disabled families stop
+    /// at the capture chokepoint at once, while UIKit observer add/remove
+    /// hops to the main thread. Reconciliation is idempotent: repeated plans
+    /// with the same semantics leave the installed observers untouched.
+    public func applyPlan(_ plan: ForgeCapturePlan) {
+        capture.applyPlan(plan)
+        runOnMain { [weak self] in
+            self?.reconcileObservers()
+        }
+    }
+
+    /// Main-thread observer reconciliation against the latest effective
+    /// features (reads the gate at execution time so rapid plan bursts
+    /// converge on the newest plan).
+    private func reconcileObservers() {
+        let features = capture.effectiveFeatures
+        // Sections: bit on installs the engine/sampler, knob changes
+        // hot-apply, bit off uninstalls and resets engine state.
+        sectionsCoordinator.reconcile(features: features)
+        // Attribution: replay the deep link retained while derivation was
+        // ineffective once the plan turns derivation on (B4 cold start).
+        reconcileRetainedDeepLink(features: features)
+        let lifecycle = features.lifecycle
+        observerStateLock.lock()
+        defer { observerStateLock.unlock() }
+        if lifecycle, !lifecycleObserversInstalled {
+            installLifecycleCapture()
+        } else if !lifecycle, lifecycleObserversInstalled {
+            removeLifecycleObservers()
+        }
+    }
+
+    private func removeLifecycleObservers() {
+        observerStateLock.lock()
+        let removed = observers
+        observers.removeAll()
+        lifecycleObserversInstalled = false
+        observerStateLock.unlock()
+        removed.forEach(NotificationCenter.default.removeObserver)
+    }
+
+    private func runOnMain(_ block: @escaping () -> Void) {
+        if Thread.isMainThread {
+            block()
+        } else {
+            DispatchQueue.main.async(execute: block)
+        }
+    }
+
+    public func screenView(_ name: String, previous: String? = nil) -> ForgeOutcome {
+        // F3 parity rule: on a real screen change, flush raw_section_hidden
+        // for still-visible sections FIRST (under the old screen context) and
+        // reset per-screen dedupe, before the new screen context lands.
+        let screenChanged = capture.currentScreenName != name
+        if screenChanged {
+            sectionsCoordinator.onScreenWillChange()
+        }
+        let screen = ScreenContext(current: name, previous: previous)
+        capture.setCurrentScreen(screen)
+        let outcome = capture.capture(eventName: RawEventName.screenView, screen: screen, foregroundState: .foreground)
+        if screenChanged {
+            sectionsCoordinator.onScreenDidChange()
+        }
+        return outcome
+    }
+
+    /// Reports an incoming deep link. Emits `raw_deep_link_received` with the
+    /// Android-parity component fields (scheme/host/path plus the url*
+    /// duplicates and the always-present `action`), then — independently of
+    /// the deep-link family outcome — derives `raw_attribution` when the plan
+    /// enables the ATTRIBUTION family with `deriveFromDeepLinks` (B4). While
+    /// derivation is ineffective (fail-closed pre-plan) the most recent URL
+    /// is retained and replayed once by plan reconciliation. The returned
+    /// outcome stays the deep-link event's outcome.
+    public func deepLink(_ url: URL, action: String? = nil) -> ForgeOutcome {
+        let outcome = capture.capture(
+            eventName: RawEventName.deepLinkReceived,
+            data: [
+                "scheme": url.scheme ?? "unknown",
+                "host": url.host ?? "unknown",
+                "path": url.path,
+                "action": action ?? "",
+                "urlScheme": url.scheme ?? "unknown",
+                "urlHost": url.host ?? "unknown",
+                "urlPath": url.path,
+                "url": PrivacySanitizer.redactUrl(url.absoluteString),
+            ],
+            foregroundState: .foreground
+        )
+        deriveAttribution(from: url)
+        return outcome
+    }
+
+    /// B4 deep-link attribution: gated by the plan family bit AND the
+    /// `deriveFromDeepLinks` knob (closed before the first plan), parsed by
+    /// the pure parser, and deduped once per exact URL per process AFTER all
+    /// other gates so a disabled sighting never consumes the URL's slot.
+    /// While derivation is ineffective the most recent URL is retained in a
+    /// single slot for the plan-reconcile replay (Android parity).
+    private func deriveAttribution(from url: URL) {
+        // Mirror the chokepoint's outer guard BEFORE the dedupe so a
+        // disabled/pre-consent sighting never burns the URL's only slot (and
+        // is never retained either while consent is missing).
+        guard configuration.enabled, configuration.consentGranted else { return }
+        let features = capture.effectiveFeatures
+        guard features.attribution,
+              let knobs = features.attributionPlan,
+              knobs.deriveFromDeepLinks else {
+            // Fail-closed today, maybe effective tomorrow: keep the most
+            // recent URL so the plan reconcile hook can replay it (the iOS
+            // cold-start campaign landing arrives before the first plan).
+            retainedDeepLinkLock.lock()
+            retainedDeepLinkWhileIneffective = url
+            retainedDeepLinkLock.unlock()
+            return
+        }
+        guard let params = AttributionDeepLinkParser.parse(
+                  url: url,
+                  extraQueryKeys: knobs.extraQueryKeys,
+                  includeLandingUrl: knobs.includeLandingUrl
+              ),
+              !AttributionDeepLinkDedupe.hasSeen(url: url.absoluteString) else {
+            return
+        }
+        let outcome = capture.capture(
+            eventName: RawEventName.attribution,
+            data: params,
+            foregroundState: .foreground
+        )
+        // The chokepoint can still reject after the gates above (plan flip
+        // window, kernel rejection): consume the URL's single slot only on an
+        // accepted emission (mirrors the Android install-referrer settle).
+        if outcome.isAccepted {
+            AttributionDeepLinkDedupe.markSeen(url: url.absoluteString)
+        }
+    }
+
+    /// Plan reconcile hook (Android `DeepLinkCapture.reconcile` parity): when
+    /// the effective plan enables deep-link derivation and a deep link was
+    /// retained while derivation was ineffective, replays the derivation for
+    /// exactly that URL. The slot clears once a derivation attempt runs under
+    /// an effective plan; ineffective plans keep the slot for a later flip.
+    private func reconcileRetainedDeepLink(features: EffectiveCaptureFeatures) {
+        guard features.attribution, features.attributionPlan?.deriveFromDeepLinks == true else { return }
+        retainedDeepLinkLock.lock()
+        let retained = retainedDeepLinkWhileIneffective
+        retainedDeepLinkWhileIneffective = nil
+        retainedDeepLinkLock.unlock()
+        guard let retained else { return }
+        deriveAttribution(from: retained)
+    }
+
+    public func interaction(eventName: String, data: [String: String]) -> ForgeOutcome {
+        var enriched = data
+        let normalized = RawEventName.normalize(eventName)
+        // tvOS remote-key/select interactions enrich from the armed dwell
+        // slot when present; caller-provided keys always win.
+        if normalized == RawEventName.remoteKey || normalized == RawEventName.select {
+            sectionsCoordinator.enrichFromDwellSlot(into: &enriched)
+        }
+        return capture.capture(eventName: eventName, data: enriched, foregroundState: .foreground)
+    }
+
+    #if canImport(UIKit)
+    /// Manual-interaction chokepoint overload accepting the interacted view:
+    /// resolves {section, sectionOrder, contentId, position} through the
+    /// sections registry (explicit registrations, markers, native ids) and
+    /// merges the fields without overwriting caller-provided keys.
+    public func interaction(eventName: String, data: [String: String] = [:], view: UIView) -> ForgeOutcome {
+        var enriched = data
+        sectionsCoordinator.enrich(view: view, into: &enriched)
+        return capture.capture(eventName: eventName, data: enriched, foregroundState: .foreground)
+    }
+
+    /// F3 sections registration facade: `track(view:name:order:)`,
+    /// `track(collectionView:...)`, `track(tableView:...)`, `untrack(view:)`.
+    public var sections: ForgeSectionsTracker {
+        sectionsCoordinator.tracker
+    }
+    #endif
+
+    private func installLifecycleCapture() {
+        observerStateLock.lock()
+        defer { observerStateLock.unlock() }
+        guard !lifecycleObserversInstalled else { return }
+        lifecycleObserversInstalled = true
+        #if canImport(UIKit)
+        observers.append(NotificationCenter.default.addObserver(
+            forName: UIApplication.didBecomeActiveNotification,
+            object: nil,
+            queue: nil
+        ) { [weak self] _ in
+            _ = self?.capture.capture(
+                eventName: RawEventName.applicationForeground,
+                foregroundState: .foreground,
+                urgent: true
+            )
+        })
+        observers.append(NotificationCenter.default.addObserver(
+            forName: UIApplication.didEnterBackgroundNotification,
+            object: nil,
+            queue: nil
+        ) { [weak self] _ in
+            _ = self?.capture.capture(
+                eventName: RawEventName.applicationBackground,
+                foregroundState: .background,
+                urgent: true
+            )
+        })
+        #endif
+    }
+
+    private func installCrashCapture() {
+        let directory = FileManager.default.urls(for: .cachesDirectory, in: .userDomainMask).first?
+            .appendingPathComponent("forge-crashes", isDirectory: true)
+        let store = CrashRecordStore(directory: directory)
+        crashStore = store
+        retryPendingCrashes()
+        crashSubscription = forge?.subscribeEvents { [weak self] event, outcome in
+            if event.eventName == "sessionstart", outcome.isAccepted {
+                self?.retryPendingCrashes()
+            }
+        }
+        ForgeCrashExceptionHandler.install()
+    }
+
+    private func retryPendingCrashes() {
+        guard let forge, let crashStore else { return }
+        for record in crashStore.loadPending() {
+            let outcome = forge.kernel.recordEvent(
+                eventName: "app_crash",
+                payload: record.payload(deliveryMode: "next_launch_retry"),
+                timestampMs: ForgeClock.nowMs(),
+                urgent: true
+            )
+            if outcome.isAccepted {
+                crashStore.markSent(record.id)
+            }
+        }
+    }
+}
+
+/// Process-wide NSException crash hook that chains to any previously installed
+/// handler (mirrors the Android `UncaughtExceptionCapture` chaining contract):
+/// Forge stores its crash record first, and the displaced handler is always
+/// invoked afterwards so other crash reporters keep receiving NSException crashes.
+enum ForgeCrashExceptionHandler {
+    private static let lock = NSLock()
+    private static var installed = false
+    private(set) static var previousHandler: (@convention(c) (NSException) -> Void)?
+
+    static func install() {
+        lock.lock()
+        defer { lock.unlock() }
+        guard !installed else { return }
+        installed = true
+        previousHandler = NSGetUncaughtExceptionHandler()
+        NSSetUncaughtExceptionHandler(forgeUncaughtNSExceptionHandler)
+    }
+
+    /// Forge-owned crash work. All persistence is best-effort (`try?` inside the
+    /// store), so a failure here never prevents the chained previous handler from
+    /// running in `forgeUncaughtNSExceptionHandler`.
+    static func storeCrashRecord(_ exception: NSException) {
+        CrashRecordStore.defaultStore.store(CrashRecord(exception: exception))
+    }
+
+    /// Test hook: clears the installed flag and the captured previous handler so
+    /// regression tests can exercise installation chaining deterministically.
+    static func resetForTesting() {
+        lock.lock()
+        installed = false
+        previousHandler = nil
+        lock.unlock()
+    }
+}
+
+/// Top-level handler so it can be expressed as a C function pointer. The previous
+/// handler invocation is unconditional: it does not depend on the outcome of
+/// Forge's own crash work.
+private func forgeUncaughtNSExceptionHandler(_ exception: NSException) {
+    ForgeCrashExceptionHandler.storeCrashRecord(exception)
+    ForgeCrashExceptionHandler.previousHandler?(exception)
+}