v10 slice 3: iOS queue store, executor, and events

[dmurphy5]

Summary

This PR makes the iOS side real. It does the same job as the Android PR, with the same rules and the same status names, so the app behaves the same on both platforms.

iOS has no WorkManager. It has a background URLSession: the system sends the request in its own process and wakes the app when the request finishes, even if the app was closed. This PR builds the queue on top of that.

How a request moves through iOS

sequenceDiagram
    participant JS
    participant Queue as Library (iOS)
    participant Session as Background URLSession (system)
    participant Server

    JS->>Queue: mutate(variables)
    Queue->>Queue: write the request and its body file to disk
    Queue-->>JS: stored
    Queue->>Session: create an upload task from the file
    Session->>Server: send (the system keeps sending if the app is suspended)
    Server-->>Session: response
    alt app is running
        Session-->>Queue: task finished
    else app was closed
        Session-->>iOS: wake the app
        iOS-->>Queue: handleEventsForBackgroundURLSession
        Queue->>Queue: reconnect the finished task to its request
    end
    Queue->>Queue: write the result to the journal
    Queue-->>JS: result event (now, or at the next startup)

Loading

The rules are the same as on Android: write the request first, retry with a growing wait, park on 401 until updateHeaders(), journal before telling JS, exactly one result per request.

What is different on iOS

1. Every upload comes from a file. The system requires it for background sessions. So JSON and multipart bodies are written to a file before the task is created.
2. Retries use delayed tasks. There is no scheduler like WorkManager. A retry is a task with a start time in the future.
3. Reconnecting after a relaunch. When the system wakes the app, the library matches each finished task to its request by a key it stored when it created the task. A task with no request, or a request with no task, is repaired at startup.
4. Force quit. If the user swipes the app away, the system cancels the session's tasks. The library sees this at the next launch and retries.
5. No global limit on parallel requests. The system limits connections per host instead.

Testing without a device

The pure logic (the store, the retry table, the status changes, the journal, the relaunch matching) is a Swift package. cd ios && swift test runs 201 tests on a Mac in about one second, including crash-in-the-middle cases. The part that talks to the real URLSession is thin and is covered by the device script.

What to look at

1. QueueCoordinator+Reconcile.swift: what happens at relaunch.
2. RetryClassifier.swift: the same table as Android.
3. ios/Tests/CoordinatorRelaunchTests.swift: the relaunch cases.

Test Plan

What's required for testing (prerequisites)?

Xcode with an iOS simulator. CocoaPods for the example app. For a device run, the example app README has the script.

What are the steps to reproduce (after prerequisites)?

cd ios && swift test                                              # 201 tests, 0 failures
cd example/RNBGUExample/ios && pod install && xcodebuild -workspace RNBGUExample.xcworkspace -scheme RNBGUExample -sdk iphonesimulator -destination 'generic/platform=iOS Simulator' build

Nothing has run on a device yet.

Compatibility

OS	Implemented
iOS	✅
Android	✅ see the Android PR

Checklist

• I have tested this on a device and a simulator
• I added the documentation in README.md
• I updated the typed files (TS)
• I've added Detox End-to-End Test(s)
• I've created a snack to demonstrate the changes

🤖 Generated with Claude Code