feat: PR3A — Instruments signposts for tunnel lifecycle profiling

[mrmidi]

PR3A — Instruments Signposts

Base: pr3/binary-diagnostics · 3 files, +144/-1

Scope

Deliberately small: no persistence, no JSON changes, no state-machine changes, no per-packet instrumentation.

Signposts

Intervals (begin/end around async operations):

Signpost	Begin	End
TunnelStartup	startTunnel entered	finishStart called
BridgeLifetime	bridge created	bridge stopped (per generation)
NativeTeardown	bridge detached	final status captured
TunnelShutdown	stopTunnel entered	completionHandler called
ReconnectDelay	reconnect scheduled	fired/cancelled

Point events (instantaneous):

TransportConnected, TransportDisconnected, NetworkPathChanged, MemoryWarning, InvariantViolation, PacketReadLoopStarted, PacketReadLoopStopped

Build config

• FPTN_SIGNPOSTS added to Debug and Measurement configs
• No signposts in Release (production)
• import OSLog guarded by #if FPTN_SIGNPOSTS

State storage

Single active bridge signpost (PR2 guarantees single exposed bridge):

#if FPTN_SIGNPOSTS
private var startupSignpost: OSSignpostIntervalState?
private var bridgeSignpost: (generation: Int, id: OSSignpostID, state: OSSignpostIntervalState)?
private var teardownSignpost: ...
private var shutdownSignpost: OSSignpostIntervalState?
private var reconnectSignpost: ...
#endif

Acceptance test

Record Allocations + VM Tracker in Instruments and verify:

TunnelStartup
BridgeLifetime generation 1
NativeTeardown generation 1
ReconnectDelay
BridgeLifetime generation 2
TunnelShutdown
NativeTeardown generation 2

Verification

• Xcode Debug build: succeeded
• Tests: 27/27 passed

Stack

PR2   Provider integration
PR3   Binary diagnostics core     (base)
PR3A  Instruments signposts       ← this PR
PR4   Shared contracts
PR5   Packet-copy reduction