perf(analytics): opt-in pause of unread snapshot recomputers #492

Purpose and priority

Evaluate an opt-in analytics.pauseWhenIdle policy that skips background snapshot recomputations nobody reads. Potential allocation/GC savings should be measured on our fork before choosing it over continuously warm caches.

Current fork

Assessed on 16 October 2026 against master b6852ba0876b02426b6200c1c79c7e0ebe3b9389. Our analytics recomputers use periodic refresh and do not expose this idle-pause option. Enumerate our actual recomputers and their dependencies: do not assume the reference's endpoint count or wiring is identical.

Proposed behavior

• Default remains off, preserving existing behavior.
• Once a successful initial snapshot exists, unused recomputers may pause. Startup loading, completion/warm-up gates and error recovery must still work.
• The first read after idle returns the existing snapshot without blocking on computation and requests one bounded/coalesced wake-up. Subsequent reads receive the refreshed snapshot.
• Document that the first post-idle result can be older than the normal interval. A stale cached result must not silently be described as freshly computed.
• Treat one recomputer reading another's snapshot as a real dependency; idle accounting must not starve dependent analytics. Preserve shutdown/join semantics and bounded channels/state.

Acceptance criteria

• Config tests prove nil/absent/false is unchanged, and explicit true reaches every applicable fork recomputer.
• Deterministic synchronization-based tests cover unread ticks, continuous reads, concurrent wake-ups, first computation, startup-load completion, failed computations and shutdown. Avoid replacing a production design with flaky sleep-based tests.
• Readers never wait for the heavy computation; a burst does not create a recomputation storm or unbounded queue.
• Run race tests and mutation checks for ignored opt-in, skipped startup work, lost wake-up and falsely fresh snapshots.
• Measure computation counts, allocations, CPU and request latency against equivalent visible/idle traffic. Reference allocation reductions are not proven savings on our deployment.
• Document the operator freshness trade-off and keep packet-database read/write separation, cache limits and fork CI/publication guards intact.

Comparison source

Literal identifiers only, intentionally without upstream hyperlinks or cross-repository references:

Source repository: Kpa-clawbot/CoreScope
Pull request number: 2164
PR head commit SHA: c1eec09c6798787233a0820e8666fca28ef99493
Upstream merged SHA: 4e91c5cf0bb2e35e12a074580f4d993c32cb6f00
Files changed:
  cmd/server/analytics_pause_when_idle_test.go
  cmd/server/analytics_recomputer.go
  cmd/server/config.go
  cmd/server/direct_heard.go
  config.example.json

Recheck master and competing work before implementation. This records investigation and acceptance criteria, not permission to enable the feature, change live configurations or deploy.