feat(rumble): host-authoritative self-terminating envelopes (0xCA v2)

Rumble was level-triggered, unbounded state on a lossy channel: a non-zero
level meant "buzz until further notice", healed only by the host re-sending
state every 500 ms, and every client guessed when the host had died with its own
magic timeout (SDL 1.5 s, Apple 1.6 s, Android up to 60 s). A lost stop, a
reordered start, or a dead host could drone the motor for seconds.

Make "stuck rumble" inexpressible on the wire. The 0xCA datagram grows a
length-tolerant tail — [u8 seq][u16 ttl_ms] — so it self-terminates: the host
authorizes a level for at most ttl_ms and renews it (~120 ms) while it holds,
letting an abandoned one lapse client-side. seq is a per-pad wrapping reorder
gate (reusing GamepadSnapshot::seq_newer) so a reordered stale start can't
re-light a stopped motor. Decoders read the first 7 bytes as a plain level and
ignore the tail, so no wire-version bump: an old client renders a new host's
levels, and a new client falls back to its prior staleness heuristic against an
old host (ttl = None). All four generation pairings render correctly.

- core: encode_rumble_datagram_v2 / decode_rumble_envelope (datagram.rs); the
  client demux applies the seq gate then forwards (pad, low, high, Option<ttl>);
  next_rumble is unchanged (drops ttl), next_rumble_ttl keeps it; ABI adds
  punktfunk_connection_next_rumble2 + PUNKTFUNK_RUMBLE_NO_TTL, ABI_VERSION 4->5
  (WIRE_VERSION unchanged — the tail is backward-compatible).
- host (punktfunk1.rs): the flat 500 ms refresh becomes a renewal loop that bumps
  seq + stamps a fresh TTL on active pads and drains a short post-stop zero burst,
  then goes quiet. Hatches: PUNKTFUNK_RUMBLE_ENVELOPE=0 (legacy v1 + flat refresh,
  a bisect switch), PUNKTFUNK_RUMBLE_TTL_MS (clamped [150, 5000]).
- renderers honor the TTL as their playback duration/deadline and keep their old
  heuristic only for a legacy (ttl=None) update: pf-client-core (the Deck haptic
  keep-alive is now deadline-bounded so it can't sustain a host-stopped rumble),
  clients/windows (SDL duration), android (JNI packs the lease out-of-band in bit
  48 so any u16 ttl is unambiguous; Kotlin createOneShot(ttl)), apple
  (RumbleRenderer.envelopeDeadline + nextRumble2; sessionStaleSeconds demoted to
  the legacy fallback).
- tests: codec round-trip + tail tolerance + seq-gate reorder (Rust); the probe
  asserts the v2 tail arrived under PUNKTFUNK_TEST_FEEDBACK; the Apple loopback
  asserts ttlMs round-trips end to end; RumbleTuning lease-decision cases.

The host-side idle-timeout from the previous commit is defense in depth on the
game side; this is the guarantee on the client side. Design:
punktfunk-planning/design/rumble-envelope-plan.md.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

clients/apple/Tests/PunktfunkKitTests/LoopbackIntegrationTests.swift

@@ -88,16 +88,19 @@ final class LoopbackIntegrationTests: XCTestCase {
         // one feedback burst on the host→client planes — drain both and verify, end to
         // end through the xcframework: rumble (0xCA) + the three hidout kinds (0xCD).
         if ProcessInfo.processInfo.environment["PUNKTFUNK_TEST_FEEDBACK"] == "1" {
-            var rumble: (pad: UInt16, low: UInt16, high: UInt16)?
+            var rumble: (pad: UInt16, low: UInt16, high: UInt16, ttlMs: UInt32)?
             var hidout: [PunktfunkConnection.HidOutputEvent] = []
             let feedbackDeadline = Date().addingTimeInterval(10)
             while (rumble == nil || hidout.count < 3), Date() < feedbackDeadline {
-                if rumble == nil, let r = try conn.nextRumble(timeoutMs: 100) { rumble = r }
+                if rumble == nil, let r = try conn.nextRumble2(timeoutMs: 100) { rumble = r }
                 if let ev = try conn.nextHidOutput(timeoutMs: 100) { hidout.append(ev) }
             }
             XCTAssertEqual(rumble?.pad, 0)
             XCTAssertEqual(rumble?.low, 0x4000)
             XCTAssertEqual(rumble?.high, 0x8000)
+            // The synthetic host emits a v2 envelope (400 ms TTL) — assert the self-terminating tail
+            // survived the full wire → C ABI → Swift path, not just the level.
+            XCTAssertEqual(rumble?.ttlMs, 400)
             XCTAssertTrue(
                 hidout.contains(.led(pad: 0, r: 10, g: 20, b: 30)),
                 "missing the scripted lightbar event: \(hidout)")

clients/apple/Tests/PunktfunkKitTests/RumbleTuningTests.swift

@@ -75,6 +75,40 @@ final class RumbleTuningTests: XCTestCase {
         renderer.stop()
     }
 
+    func testLeaseSecondsInterpretsWireTTL() {
+        // The legacy no-lease sentinel → nil (fall back to the staleness watchdog).
+        XCTAssertNil(RumbleTuning.leaseSeconds(ttlMs: RumbleTuning.noTTL))
+        XCTAssertEqual(RumbleTuning.noTTL, UInt32.max)
+        // A real lease → its duration in seconds.
+        XCTAssertEqual(RumbleTuning.leaseSeconds(ttlMs: 400), 0.4, accuracy: 1e-9)
+        XCTAssertEqual(RumbleTuning.leaseSeconds(ttlMs: 0), 0, accuracy: 1e-9)
+        XCTAssertEqual(RumbleTuning.leaseSeconds(ttlMs: 150), 0.15, accuracy: 1e-9)
+    }
+
+    func testEnvelopeLeaseBoundsMotorLifeTighterThanTheLegacyWatchdog() {
+        // The whole point of v2: a host-supplied lease silences the motor faster than the
+        // legacy staleness watchdog ever could (which needs sessionStaleSeconds of silence). The
+        // default 400 ms TTL is well under that, on every platform.
+        let defaultTTL = RumbleTuning.leaseSeconds(ttlMs: 400)
+        XCTAssertNotNil(defaultTTL)
+        XCTAssertLessThan(defaultTTL!, RumbleTuning.sessionStaleSeconds)
+        // The ticker must be able to observe an expired lease promptly (well within one TTL).
+        XCTAssertLessThan(RumbleTuning.tickSeconds, defaultTTL!)
+    }
+
+    /// A v2 envelope with a short TTL, left unrenewed, must self-silence — the renderer's core
+    /// promise. Drive the real queue/ticker (no physical pad) and confirm it doesn't wedge.
+    func testEnvelopeExpiresWhenUnrenewed() {
+        let renderer = RumbleRenderer(policy: .session)
+        renderer.retarget(nil)
+        // A 100 ms lease, then no renewal — the ticker (50 ms) must silence it on its own.
+        renderer.apply(low: 0x8000, high: 0x8000, ttlMs: 100)
+        Thread.sleep(forTimeInterval: 0.3)
+        // No assertion on private state; this exercises the expiry path + serial-queue teardown
+        // without deadlock (the ticker fires on the same queue stop() sync-hops onto).
+        renderer.stop()
+    }
+
     func testTuningRelationsTheDesignDependsOn() {
         // The watchdog must tolerate a couple of lost 500 ms host refreshes (heals, not gaps)
         // but trip well before a stuck rumble reads as "still going".