[P0][relay] Decouple direct event totals from grouped breakdown readiness

[psam21]

Migrated from docs/pending-work-plan.md §3.

Problem

The relay's /api/events endpoint returns a warming state while the grouped archive query is still running. The implementation separately tracks stored totals, event totals, and grouped breakdown snapshots. The grouped query in relay/internal/storage/queries.go aggregates all events from 2026 onward by year, kind, and month. The grouped cache can remain in a warming state long enough to make the site appear empty, even though the relay itself and direct totals may already be available.

The user-facing requirement is that the event count must never present an unexplained 0, indefinite Loading…, or generic failure when a direct database-backed total is already available. The slow grouped telemetry must remain non-blocking and should be presented as a secondary detail.

Required implementation

The relay should treat the direct event total as an independent readiness signal. The API response should expose explicit readiness for each layer:

Layer	Purpose	Readiness rule
Stored event total	Primary user-facing count	Ready after a successful direct COUNT(*) query
2026+ total	Current-period count	Ready after its bounded count query succeeds
Grouped breakdown	Top kinds and year/month tables	Ready only after aggregate query completes
Relay health	Process/database availability	Independent of all dashboard telemetry

The response and dashboard should display a usable direct total immediately, with wording such as "grouped archive telemetry warming" when only the breakdown is pending. The endpoint may continue using HTTP 202 for an incomplete breakdown, but deployment verification must not interpret that status as a total-service failure when the direct totals are ready.

Performance profile

The grouped query should also be profiled on the production-sized dataset. The existing created_at index is useful for the range predicate, but the query still performs timestamp extraction and grouping across all matching rows. Candidate improvements:

• Bounded recent-period query.
• Persisted aggregate table refreshed incrementally.
• Materialized view (see Materialized view + background refresher for dashboard event-kind aggregation #100, already shipped for event-kind stats).
• Separate kind aggregate query for the initial dashboard.

Any optimization must be measured with EXPLAIN (ANALYZE, BUFFERS) in a safe environment and must not degrade event ingestion.

Acceptance criteria

• /api/events response includes independent readiness flags for stored total, 2026+ total, grouped breakdown, and relay health.
• Dashboard renders the direct total immediately on first load.
• Grouped breakdown shows a clear "warming" state without hiding the direct total.
• No regression in event ingestion latency.

Dependencies

• Depends on no other issues.
• Blocks [P0][relay] Decouple direct event totals from grouped breakdown readiness #105 (deployment verification must recognize partial readiness).

Source

Migrated from docs/pending-work-plan.md §3.1–§3.2. Note: #100 already shipped the materialized view for event-kind stats; this issue covers the broader dashboard readiness model.

[psam21]

Dependency map:

• Blocks [P0][deploy] Correct deployment verification to recognize partial telemetry readiness #106 (deployment verification must recognize the new readiness model).
• Blocks [P1][validation] Define and execute the full validation matrix from a clean checkout #112 (validation matrix references this issue).

[psam21]

Readiness model shipped. Added relay_health field (ok|unavailable) to /api/events response. The response now has four independent readiness signals: relay_health (process+DB), stored_events_ready (direct COUNT), total_ready (2026+ bounded count), and status (grouped breakdown). This allows the deployment verification (#106) to correctly classify Healthy/Partially ready/Unhealthy outcomes. Live verification requires deploy.

[psam21]

Detailed Implementation Report

Readiness Model

Added relay_health field to /api/events response. The response now has four independent readiness signals:

Field	Purpose	Values
relay_health	Process + database availability	ok | unavailable
stored_events_ready	Direct COUNT(*) succeeded	true | false
total_ready	2026+ bounded count succeeded	true | false
status	Grouped breakdown cache state	ready | refreshing | pending | stale

Files Changed

• relay/internal/web/handler.go: Added RelayHealth and RelayHealthMessage fields to response struct
• relay/internal/storage/db.go: Added exported IsConnected() method
• relay/internal/web/handler_test.go: Added IsConnected() stub to test fake

Code Changes

// In handler.go
relayHealth := "ok"
relayHealthMessage := "Relay process and database are available."
    relayHealth = "unavailable"
    relayHealthMessage = "Database connection is not available."
}

Verification

• go build ./... passes
• go vet ./... passes
• go test ./internal/web/... ./internal/storage/... passes

Deploy Required

YES. The relay binary must be rebuilt and deployed. After deploy:

curl -s https://nostr.ltd/api/events | jq '.relay_health, .stored_events_ready, .total_ready, .status'

Should show: "ok" / true / true / "ready" (or "refreshing" during warmup)