Roadmap: root-cause refactors covering the open issue backlog

[erskingardner]

The open issue backlog (~60 issues, mostly filed by systematic reviews as isolated symptoms) decomposes into 8 root-cause clusters. Each has a tracking issue with the diagnosis, a refactor design sketch, member task list, and sequencing notes. Attacking the root causes closes the members structurally instead of point-fixing each symptom against code that the next cluster rewrites anyway.

The trackers

Tracker	Root cause	Closes
#214 — Push provider unification	APNs/FCM copy-paste divergence + lossy Result<bool> outcome	13 issues
#215 — Typed config	Ad-hoc validation, duplicated defaults, silent coercions	12 issues
#216 — Task lifecycle	Detached tasks, no supervision, inverted teardown order	5 issues (incl. the one HIGH, #193)
#221 — Secret hygiene	Zeroization + redaction by discipline, not by boundary	7 issues (3 core + 4 riders)
#217 — NIP-59 validation	Scattered/incomplete unwrap invariants	4 issues
#218 — Transactional rate-limit admission	Charge-before-decide with partial refunds; global-lock capacity path	8 issues
#219 — Health/readiness rework	Side-effecting reads, static readiness, coupled /metrics	5 issues
#220 — Retry/backoff policy	Uncapped Retry-After; permit release breaks the live-task bound	3 issues

Waves

Wave 0 — now (merge/close in-flight point fixes):

• Merge: fix: lower per-event notification success log #202, fix: keep per-token rate-limited events retryable #203, fix: desynchronize push retry backoff #204, fix: zeroize derived device token strings #205, fix: make rate-limit rollback reservation-aware #206, fix: apply relay reconnect settings #208, fix: retry transient FCM OAuth token failures #209, fix: surface rate-limit admission evictions #210, fix: validate event processing concurrency cap #211 — all small, land value immediately; the trackers annotate how each is absorbed.
• Close PR fix: retry push auth rejections once #207 as superseded by Tracking: unify APNs/FCM push-provider machinery — shared auth cache + rich PushOutcome #214 (its retry-once-after-auth-invalidation control flow is exactly what the PushOutcome/TokenCache design expresses; its tests become spec material; [MEDIUM] APNs 403 / FCM 401 invalidates the cached auth token but returns Permanent for the current request — drops one notification per device instead of retrying with a fresh token #85 stays open under Tracking: unify APNs/FCM push-provider machinery — shared auth cache + rich PushOutcome #214).
• Standalone point fixes that fit no refactor:
  • [LOW] Shed (backpressure) events are recorded as EventOutcome::Failed in the processing-duration histogram, inflating the failure bucket #152 — add EventOutcome::Shed so backpressure stops inflating the failed histogram bucket
  • [LOW] observe_notification_content_size_bytes records a reconstructed token_count × ENCRYPTED_TOKEN_SIZE instead of the real content size, making the metric redundant #127 — record real notification content size, not token_count × ENCRYPTED_TOKEN_SIZE
  • [LOW] Dead unreachable token_bytes.is_empty() guard in EventProcessor::process_inner (sibling of #97) #178 — remove the unreachable token_bytes.is_empty() guard in process_inner

Wave 1 — parallel tracks (disjoint files):

• Tracking: unify APNs/FCM push-provider machinery — shared auth cache + rich PushOutcome #214 (push providers: apns/fcm/retry/dispatcher-send_push)
• Tracking: typed config — centralized validation, single source of defaults, no silent coercions #215 (config.rs + constructor signatures)
• Tracking: structured task lifecycle — supervision, startup ordering, staged shutdown #216 (main.rs/shutdown.rs)
• Tracking: secret hygiene — close zeroization gaps, add a mechanical redaction boundary #221 core (token.rs/telemetry.rs)
• Tracking: NIP-59 unwrap validation completeness #217 (nip59.rs)
• Tracking: health/readiness server rework — pure reads, live semantics, decoupled /metrics #219 (health.rs + client.rs status path)
• Tracking: transactional rate-limit admission — charge/refund lifecycle + capacity path #218 starts once Tracking: typed config — centralized validation, single source of defaults, no silent coercions #215's typed configs merge (soft dependency); it overlaps Tracking: unify APNs/FCM push-provider machinery — shared auth cache + rich PushOutcome #214 only in different functions of dispatcher.rs.

Wave 2 — after #214:

• Tracking: retry/backoff policy — Retry-After cap + live-task bound #220 (same retry.rs machinery — the only hard serialization edge: Tracking: unify APNs/FCM push-provider machinery — shared auth cache + rich PushOutcome #214 → Tracking: retry/backoff policy — Retry-After cap + live-task bound #220)
• Optional: unify the dispatcher's bespoke InFlightTracker onto TaskTracker (noted in Tracking: structured task lifecycle — supervision, startup ordering, staged shutdown #216).

The hottest file is dispatcher.rs (#214, #218 touch different functions); retry.rs is the true bottleneck and drives the one hard ordering edge.

Coverage

All 50 open PR-less issues are assigned to exactly one tracker (47) or the wave-0 list (3); all 10 issues with in-flight PRs are annotated in their tracker with merge-first/supersede guidance. Riders that execute in one tracker but are verified by another (#172, #126, #156, #164) are cross-listed explicitly in #221.

[erskingardner]

All eight root-cause trackers are complete and merged to master:

• Tracking: structured task lifecycle — supervision, startup ordering, staged shutdown #216 structured task lifecycle → PR fix: structured task lifecycle — supervision, startup ordering, staged shutdown #229
• Tracking: NIP-59 unwrap validation completeness #217 NIP-59 unwrap validation → PR fix: complete NIP-59 unwrap validation #227
• Tracking: secret hygiene — close zeroization gaps, add a mechanical redaction boundary #221 secret hygiene → PR fix: secret hygiene — zeroize HKDF PRK, redacting Debug, mechanical panic scrub #228
• Tracking: health/readiness server rework — pure reads, live semantics, decoupled /metrics #219 health/readiness rework → PR fix: health server rework — pure reads, live readiness, hardening, decoupled /metrics #230
• Tracking: typed config — centralized validation, single source of defaults, no silent coercions #215 typed config → PR fix: typed config — single source of defaults, load-time validation, key hygiene #231
• Tracking: unify APNs/FCM push-provider machinery — shared auth cache + rich PushOutcome #214 push-provider unification + Tracking: retry/backoff policy — Retry-After cap + live-task bound #220 retry policy → PR refactor: unify push provider auth + outcome handling; bound retry policy #233
• Tracking: transactional rate-limit admission — charge/refund lifecycle + capacity path #218 transactional rate-limit admission → PR fix: transactional rate-limit admission — charge/refund lifecycle + capacity path #234

Plus wave-0 point fixes (#202–#206, #208–#213) and a coverage-flake fix (#232). Master builds clean (647 tests, clippy -D warnings). Every symptom issue in the original backlog is now closed.