refactor(roadflare): decouple ride-on-demand from key state + actually-filter mute

[variablefate]

Summary

Today the RoadFlare key handshake conflates two concerns:

1. Privacy: who can decrypt my live location (Kind 30014).
2. Function: who can effectively send me a ride offer.

These should be independent. The privacy gate is legitimate. The functional gate is an accidental consequence of the rider's UI showing a stale-key driver as offline. Independently, the lightweight mute (#80) does NOT actually filter offers — muted riders still appear in the driver's inbox. Combined effect: mute is too weak for what users expect, and stale-key state silently kills ride-on-demand.

This issue rolls two corrections into one refactor.

Background

Per ADR-0008, fare calculation no longer depends on driver location — fare_fiat_amount is computed by the rider from pickup→dropoff. So the driver's live location is purely a UX/proximity feature, not load-bearing for the ride flow. The strict key-required gate predates ADR-0008 and was sized for a stricter privacy model than the codebase actually maintains today.

After PR #81, two mute concepts coexist:

• Heavyweight ("Remove") — adds to MutedRider, rotates RoadFlare key.
• Lightweight ("Mute") — sets RoadflareFollower.mutedAt, suppresses key delivery.

Neither concept currently filters incoming Kind 3173 offers from the muted pubkey.

Design

Scope A: Mute filters at the receive side

Add a sender-pubkey check against both mute lists in:

• Kind 3173 (Ride Offer) handler — drop silently before adding to driver's offer inbox. Twitter-style silent mute.
• Kind 3189 (Driver Ping) handler — same. Muted rider can't wake the driver up.
• Kind 3187 (Follow Notification) — already correct (PR fix(drivestr): treat Kind 3187 as delivery-retry, never rotate #79).
• Kind 3188 (Key Ack) — already correct (PR feat(drivestr): per-follower lightweight mute (#80) #81).

Helper: RoadflareKeyManager.isAnyMuted(pubkey) returning true if pubkey is in state.muted OR any follower row has mutedAt != null for it. Replace ad-hoc combined checks across the codebase.

Scope B: Stale-key riders can still request rides

Today the rider detects stale-key via key_updated_at mismatch in Kind 30012 and treats the driver as offline. New behavior:

• New rider-side state: LOCATION_STALE distinct from OFFLINE. UI shows the driver as available but with a "location pending" indicator.
• Allow the request flow from LOCATION_STALE. Distance/ETA panel shows a placeholder until key recovers.
• When sending the request, atomically also send a Kind 3188 with status="stale". Driver receives both — the offer goes into the inbox; the ack handler triggers a Kind 3186 re-delivery in the same beat. Rider has the new key by the time the ride starts.
• If driver is offline entirely, the offer sits unanswered like any other no-response offer (no special UX needed).

Edge case: rider has no key at all (never received one — fresh approval, key share lost). Same flow works — Kind 3188 with status="missing" instead of "stale".

Out of scope (separate issues)

• Android fiat fare wiring on receive side (drivestr) and roadflare-rider — see follow-up.
• Verifying Android fare calc never needs driver location — see follow-up.
• Renaming the heavyweight/lightweight mute APIs — naming refactor, deferred.

Acceptance criteria

• Driver-side: muted rider's Kind 3173 offers don't appear in offer inbox; RoadflareWiringTest or new test pins this.
• Driver-side: muted rider's Kind 3189 driver pings drop silently; rate-limiter dedup confirmed unaffected.
• Single isAnyMuted(pubkey) helper used by all four handlers (3173, 3187, 3188, 3189).
• Rider-side: LOCATION_STALE UI state shows driver as available but with location-pending indicator.
• Rider-side: requestRide() succeeds from LOCATION_STALE; sends Kind 3188 stale-signal alongside the offer.
• Driver-side: receiving an offer from a follower whose key_updated_at is behind triggers Kind 3186 re-delivery.
• Regression tests: stale-key offer arrives at driver with same payload shape as fresh-key offer; muted-rider offer is dropped in driver's offer-receive callback (not just hidden in UI).
• Manual: drivestr + 2 rider clients. Mute rider A. Have A send a request → A sees no response, B is unaffected. Then "Remove" A → A's stored key is invalidated by rotation, B continues normally.
• Manual: drivestr offline for >12h, follower comes back online and tries to request → request succeeds, driver responds when next online, key recovery completes inline.

Privacy + UX caveats

• Silent mute means the muted rider has no way to know they're muted. They keep retrying. This is the standard "soft block" UX (Twitter, Instagram). Documenting as a deliberate choice.
• LOCATION_STALE showing as "available" gives slightly weaker offline-driver clarity. Mitigation: subtle UI hint ("location updating" sub-label). Definitely better than the current funnel-killing "offline."
• The Kind 3188 stale-signal-with-offer combo means a request can leak the rider's pubkey to a driver whose key is rotated specifically to exclude them. But: the rider was already going to send that signal as soon as their app comes back online and detects staleness — this just batches it with the offer. No new privacy leak.

Related

• Driver-side mute feature: per-follower MUTED state with Kind 30177 backup field #80 — Per-follower lightweight mute (introduced the second mute concept).
• fix(drivestr): treat Kind 3187 as delivery-retry, never rotate #79 — Kind 3187 delivery-retry fix (introduced staleness-aware key re-delivery via Kind 3188).
• Drivestr: Kind 3187 follow-notification triggers full key rotation; should re-deliver existing key on re-add #78 — Original Kind 3187 key-rotation issue.
• ADR-0008 — Authoritative fiat fare on Kind 3173. Shows that driver location is no longer required for fare calc, which is the root reason this decoupling is now safe.

[variablefate]

Dependency on #83

Per the comment on #83, Android rider-app's RoadFlare fare currently includes the driver→pickup leg (`calculateRoadflareFare` at `RiderViewModel.kt:1486`), so a rider with a stale key cannot compute the same fare a fresh-key rider would. That breaks Scope B's premise that "the offer carries an authoritative fare regardless of key state."

Order of operations:

1. fix(rider-app): wire per-driver-fare fallback to also cover stale/missing key case #83 lands first — port iOS rider-route-only fare model so fare doesn't depend on driver location.
2. refactor(roadflare): decouple ride-on-demand from key state + actually-filter mute #82 follows — at that point, a rider with stale key can compute the same authoritative fare as a fresh-key rider; Scope B's offer-from-stale-key flow becomes correct.

Could parallelize by gating Scope B behind "if iOS-style fare model is in effect" — but that introduces a temporary mode flag and is more code than just sequencing the work. Recommend doing #83 first.

Scope A (mute filters at receive side) does NOT depend on #83 — could be split out and shipped first if there's pressure to ship the silent-mute UX independently.

[variablefate]

Updated dependency on #83 (2026-05-05)

User decided: keep per-driver fare on Android, add fallback only for the no-location-available case. The fallback ALREADY exists in RiderViewModel.kt:1758-1762 and calculateFare is already the iOS-style model.

So #83 reduces to: "surface stale-key drivers as available, pass driverLocation = null to the offer call, and add a UI hint that the fare is an estimate." Small wiring change, not a fare-model port.

Net effect on this issue: #82 is no longer blocked. Scope B can be implemented in parallel with #83 or fold the small #83 wiring change into #82's PR. The fallback path is the iOS-style fare via state.fareEstimate — same number a rider with a fresh key would see in the no-location case.

Scope A (mute filters at receive side) remains independent of either.

[variablefate]

Updates (2026-05-05)

Two simplifications based on protocol-level findings + UX decision:

Schema work eliminated

`RoadflareLocationEvent.create()` already emits `status` as a public tag (alongside `key_version` and `expiration`). Only `lat`, `lon`, `timestamp`, and `onRide` are in the encrypted content. Helper `getStatus(event)` at L163 reads the public status without any decryption.

So a stale-key follower can already see "this driver is online" — they just can't decrypt the location. No new field, no schema change, no backwards-compat work. The protocol already supports the design.

Drop the LOCATION_STALE UI state

The earlier scope had a `LOCATION_STALE` UI state with a "location pending" indicator. Pulling it. Driver just shows as available; the fare fallback (already in code per #83) handles the missing-location case silently. iOS doesn't have this UI either and doesn't need it.

Updated Scope B

• Rider-side: subscribe to Kind 30014 events from followed drivers regardless of key state. Use the public `status` tag (`getStatus(event)`) to determine availability when content can't be decrypted.
• When sending an offer to a stale-key driver, pass `driverLocation = null` to `sendRoadflareOffer` — existing fallback at `RiderViewModel.kt:1761` produces the iOS-style rider-route fare. No UI hint needed.
• Send a Kind 3188 with `status="stale"` alongside the offer so the driver re-delivers the current key in the same beat.
• No new UI state. No "location pending" indicator. Driver appears available exactly as if their location were fresh.

Scope A (mute filter) is unchanged. The single `isAnyMuted(pubkey)` helper for Kind 3173 / 3187 / 3188 / 3189 still applies.