feat: PR2 — provider integration, invariants, fallback reconnect gating

[mrmidi]

PR2 — Wrapper/Provider Integration

Base: pr1c/teardown-ownership (stacked PR chain)
Files: 6 — 468+/63-

Provider invariants

• ProviderInvariant enum: multipleNativeClients, incompleteNativeTeardown
• Logged once per type via logInvariantOnce()
• Checked via native status after teardown (liveClients > 1, activeOperations != 0)

Bridge lifecycle safety

• replaceWebSocketClient returns Bool, accepts expectedGeneration
• Validates generation BEFORE detaching and BEFORE exposing
• Rejects new-client installation during shutdown; removal always allowed
• WebsocketClientBridge has one-shot lifecycle latch (created→started→stopped)
• Once stop() wins, start() is permanently rejected — no resurrection
• startWebSocket uses stopCurrent: true, stopOrigin: .swiftReconnect

Packet read ownership

• PacketReadToken(session:generation:) with process-lifetime tunnelSession
• Exactly one process-wide pending read (pendingReadToken == nil guard)
• Only the owning callback clears the slot
• Stale callback restarts current generation's read loop
• stopTunnel does NOT clear pending-read state

Final native status preservation

• lastNativeStatus captured AFTER stop/join (not before)
• currentSnapshot() queries native status outside stateLock
• Falls back to saved status when no live client attached

TunnelRuntimeSnapshot — all PR1A–1C fields

16 new fields: socket buffers, lifecycle counters, queue diagnostics, disconnect code/origin, active operations, stop cleanup status

VPNService fallback reconnect

• Cancellable Task<Void, Never>? (cancelled on connected/connecting/reasserting/disconnect)
• FallbackReconnectDecision: doNotReconnect / reconnectNow / recheckAfter
• Recheck loop for fresh heartbeat (not single evaluation)
• Typed heartbeat fields (localStopInitiator, nativeDisconnectCode, nativeStopOrigin)
• Controlled-stop check uses correct raw values (app_disconnect, system_stop)
• Budget off-by-one fixed (N allows N attempts)
• Rechecks NE status after sleeping

Heartbeat typed fields

Optional backward-compatible fields on TunnelProviderHeartbeat. Old persisted heartbeats still decode.

Verification

• Xcode Debug build: succeeded
• Tests: 27/27 passed (3 new PR2 tests: enum mapping, typed heartbeat, backward compat)

Stack

PR-1  Measurement safety
PR0   Production native build
PR1A  Native fixed baseline
PR1B  Queue and batch bounds
PR1C  Native teardown ownership   (base)
PR2   Provider integration        ← this PR
PR3   C-based binary flight recorder