comunidadhll/ai/tasks/done/TASK-054-historical-snapshots-prewarm-and-cache-policy.md

TASK-054-historical-snapshots-prewarm-and-cache-policy

Goal

Preparar una política operativa de prewarm y refresco de snapshots históricos para que los servidores y métricas más visibles ya estén listos antes de que el usuario abra la página, reduciendo tiempos de espera al cambiar de servidor o pestaña.

Context

Aunque la UI deje de precargar agresivamente en el navegador, sigue siendo útil que el backend mantenga calientes y listos los snapshots más importantes. Esto debe hacerse de forma controlada y periódica, sin volver a un modelo de recomposición bajo demanda. Además, conviene definir mejor la política de caché frontend para que ayude sin dejar resultados vacíos obsoletos demasiado tiempo.

Steps

1. Revisar la generación actual de snapshots y el runner periódico.
2. Definir qué snapshots deben considerarse prioritarios para prewarm, como mínimo:
   • server-summary para #01, #02, #03 y all-servers
   • leaderboard semanal de la métrica por defecto para #01, #02, #03 y all-servers
   • recent-matches para #01, #02, #03 y all-servers
3. Diseñar e implementar una estrategia de prewarm ligera y razonable para esos snapshots prioritarios.
4. Mantener la generación de otras métricas de leaderboard de forma periódica o diferida, según convenga, pero sin penalizar la primera carga de la UI.
5. Revisar y ajustar la política de caché frontend para:
   • aprovechar respuestas recientes
   • no mantener indefinidamente respuestas vacías antiguas
   • permitir que el usuario vea mejoras sin necesidad de comportamientos raros
6. Documentar la estrategia operativa de prewarm y caché.
7. No convertir esta task en una optimización prematura excesiva; mantener el alcance claro y pragmático.
8. Al completar la implementación:
   • dejar el repositorio consistente
   • hacer commit
   • hacer push al remoto si el entorno lo permite

Files to Read First

• AGENTS.md
• backend/README.md
• backend/app/config.py
• backend/app/historical_runner.py
• backend/app/historical_snapshots.py
• backend/app/historical_snapshot_storage.py
• frontend/assets/js/historico.js
• docs/historical-coverage-report.md

Expected Files to Modify

• backend/app/config.py
• backend/app/historical_runner.py
• backend/app/historical_snapshots.py
• frontend/assets/js/historico.js
• backend/README.md
• opcionalmente documentación técnica adicional si ayuda a dejar la política operativa clara

Constraints

• No volver a recomposición pesada en request path.
• No crear páginas nuevas.
• No romper la UI histórica existente.
• No introducir frameworks nuevos.
• No hacer cambios destructivos.
• Mantener el trabajo centrado en snapshots listos antes de la interacción del usuario.

Validation

• Existe una estrategia clara de prewarm de snapshots prioritarios.
• Cambiar de servidor o entrar en la página es más rápido que antes.
• La política de caché frontend es más sana y coherente con el uso real.
• La documentación refleja la nueva operativa.
• Los cambios quedan committeados y se hace push si el entorno lo permite.

Change Budget

• Preferir menos de 5 archivos modificados o creados.
• Preferir menos de 220 líneas cambiadas.

Outcome

• El runner histórico ya no duplica una recomposición completa de snapshots tras cada refresh incremental.
• La operativa periódica hace prewarm en cada ciclo para server-summary, weekly-leaderboard de kills y recent-matches en comunidad-hispana-01, comunidad-hispana-02, comunidad-hispana-03 y all-servers.
• La matriz completa de métricas queda en una cadencia separada configurable con HLL_HISTORICAL_FULL_SNAPSHOT_EVERY_RUNS, evitando penalizar cada refresh.
• La caché frontend ahora distingue snapshots frescos, stale y missing para conservar respuestas útiles más tiempo sin retener vacíos antiguos indefinidamente.
• Validación local:
• py_compile sobre config.py, historical_snapshots.py, historical_ingestion.py, historical_runner.py y payloads.py
• node --check frontend/assets/js/historico.js
• validación funcional con SQLite temporal: priority-prewarm -> 12 snapshots y full-matrix -> 6 snapshots para un servidor
• la generación contra el dataset histórico real superó el timeout local de la consola, por lo que la validación operativa completa quedó acotada a la ruta temporal