Arquitectura

Si vas a cambiar comportamiento, empieza aquí. Si vas a cambiar texto, solo necesitas Announcements.py.

Capas

                     Announcements.py        ← todo el texto, recompensas y colores
                            │
                     hell/texts.py           ← lo carga, lo recarga en caliente, nunca falla por él
                            │
  ┌─────────────────────────┴───────────────────────────────────────────┐
  │  NÚCLEO PURO — sin imports de Discord, testeable de forma unitaria   │
  │                                                                      │
  │  timeline.py    reloj global del evento         0 → 160h             │
  │  tracking.py    relojes de sesión por usuario   0 → Xh cada uno      │
  │  grace.py       ventana de gracia del canal     máquina de 15s       │
  │  milestones.py  tabla de hitos y consultas                           │
  │  leaderboard.py clasificación, empates, podio                        │
  │  reports.py     fichas de estadísticas finales                       │
  │  alivecheck.py  programación y resolución del pase de lista          │
  │  engine.py      la máquina de estados que une todo lo anterior       │
  │  storage.py     persistencia SQLite de todo ello                     │
  └─────────────────────────┬───────────────────────────────────────────┘
                            │  entra Observation · sale DomainEvent
  ┌─────────────────────────┴───────────────────────────────────────────┐
  │  BORDE DE DISCORD                                                    │
  │                                                                      │
  │  monitor.py     sondeo del canal a 1s, ediciones de progreso         │
  │  embeds.py      cómo se ve cada mensaje                              │
  │  announcer.py   cómo se entrega cada mensaje                         │
  │  aliveio.py     pings, expulsiones y recuperación de respuestas      │
  │  dm.py          entrega de las fichas de estadísticas                │
  │  logsink.py     flujo de log en vivo a los MD del operador           │
  │  cog.py + ui.py comandos de barra, confirmaciones, permisos          │
  │  health.py      preflight de arranque (IDs, permisos, intents)       │
  │  bot.py         cableado y ciclo de vida                             │
  └──────────────────────────────────────────────────────────────────────┘

launcher/ es un front-end de escritorio separado (envfile.py para la E/S de configuración, runtime.py para el hilo supervisor, gui.py para la ventana Tk). Importa el bot; el bot nunca lo importa a él.

Mapa de módulos

El paquete hell/ son 41 módulos. Están agrupados por lo que hacen, con la responsabilidad real de cada uno tal como la declara su propio docstring.

Entrada, configuración y arranque

Motor, tiempo y progresión

Las dos líneas de tiempo están separadas a propósito: la del evento es absoluta y compartida, y la de cada usuario solo cuenta lo que se ha observado de verdad.

Observación del canal de voz

Persistencia

Comandos, mensajes y apariencia

hell/cog.py es con diferencia el módulo más grande del paquete (115 KB): concentra el manejo de comandos, que es donde más superficie de Discord se toca.

Informes, clasificación y comunicación

Seguridad y robustez

Estado público

Los tres forman la cadena del panel público: el estado interno se escribe en status.json, se sirve en vivo por WebSocket y se publica en Pages.

Los textos

Announcements.py, en la raíz del repositorio y con 40 KB, es el único archivo que contiene todos los mensajes del bot. hell/texts.py se limita a cargarlo, y hell/milestones.py aporta la estructura sin los textos.

Salud del contenedor

tools/healthcheck.py responde a una pregunta concreta: ¿está el bot vigilando de verdad el canal de voz? Sale con 0 si está sano y con 1 si no, que es lo que hace que Docker o systemd lo reinicien.

Lo interesante es qué mira: el archivo de estado, no el proceso. Un proceso vivo cuyo bucle de monitorización se ha quedado atascado es peor que uno que ha fallado, porque el evento sigue corriendo mientras nadie observa el canal. Así que si hay un evento en marcha y la última observación es más antigua que el retraso permitido (--max-lag), el bot se declara no sano.

Los once invariantes

1. El tiempo es absoluto. Todo cálculo usa marcas POSIX; nada depende del tiempo de vida del proceso, así que un reinicio no puede desplazar ni resetear el cronómetro.
2. El reloj nunca pasa de 160 h. EventTimeline.clamp() se aplica antes de usar o guardar cualquier valor de tiempo transcurrido.
3. Un estado terminal es terminal salvo reanudación explícita. Una vez en FAILED, COMPLETED o CANCELLED, los ticks son inertes y la clasificación está congelada; solo /hell reset lo limpia, o /hell resume con MFA del operador para continuar una partida fallida.
4. Un hito se dispara exactamente una vez. INSERT OR IGNORE decide el ganador; announced solo se activa después de que Discord acepte el mensaje, así que un fallo entre ambos pasos lo vuelve a publicar en vez de perderlo.
5. Solo se acredita tiempo observado, con tope por tick (MAX_TICK_CREDIT_SECONDS), para que una caída nunca se pague en silencio. Con una excepción deliberada: una caída más corta que DOWNTIME_CREDIT_SECONDS se devuelve a los usuarios vistos en el canal antes y después, porque demostrablemente nunca se fueron.
6. Los bots y los @clanker no existen para el núcleo: el monitor los filtra antes de construir una Observation.
7. Un canal vacío abre una ventana de gracia, no un fallo inmediato, y el fallo se marca con la hora del momento en que el canal se vació, nunca más tarde. Si una comprobación de vida deja el canal vacío, se usa una gracia de recuperación de 2 minutos en vez de la ventana normal de 15 segundos.
8. Nada en la ruta de mensajes puede romper el evento. Texto malo, placeholder ausente, envío fallido, MD cerrado: todo se registra, nada es fatal.
9. El trabajo en segundo plano nunca bloquea el bucle de un segundo. La E/S del pase de lista y la entrega de MD pasan por hell/tasks.spawn(), que además registra los fallos.
10. Orden seguro ante fallos: la base de datos nunca queda contradiciendo a Discord. Cada operación con estado escribe su fila antes de la llamada a la API de Discord que depende de ella, y limpia (o marca pending) si falla.
11. La pausa es un desfase, no una parada. /hell pause no cambia el estado del evento: registra paused_ts y acumula paused_seconds en la fila event. Cada lectura de hora se convierte con _effective_now() (now − paused_seconds − pausa en curso).

El invariante 10 en detalle

Es el que sostiene todo lo demás:

• La expiración de la gracia ejecuta _terminate(FAILED) —un único save_state que fija status y limpia grace_started_ts— antes de cualquier limpieza en memoria, así que un fallo nunca puede dejar el evento en RUNNING sin ventana.
• Una comprobación de vida se persiste en alive_check antes de llamar a send_check. Un envío fallido borra la fila tentativa (nunca «la BD dice activa, Discord dice que no existe») y un envío correcto va seguido de una segunda escritura con el channel_id y el message_id reales. Una excepción de send_check (error de red) limpia exactamente igual que un resultado None, así que ninguna comprobación fantasma puede expulsar después a gente que nunca vio un pase de lista.
• La resolución escribe alive_check_history y limpia la fila pendiente antes de expulsar a nadie, así que un fallo a mitad de la expulsión deja un historial resoluble y ninguna comprobación pendiente obsoleta.
• Cada MD de ficha se registra en dm_log como pending antes de la llamada y se actualiza a sent, blocked o failed después, así que un fallo a mitad de la entrega reintenta exactamente a los destinatarios correctos y nunca vuelve a escribir a nadie marcado como sent.

El invariante 11 en detalle

Mientras está pausado, las dos cronologías se detienen, los hitos, la gracia y el completado quedan inertes, y tras /hell resume los relojes continúan exactamente donde se pararon. Una ventana de gracia abierta se desplaza hacia delante por la pausa al reanudar, así que su cuenta atrás sigue con el tiempo que le quedaba. Un reinicio estando pausado vuelve pausado, y el healthcheck del contenedor trata un evento pausado como sano: un last_tick_ts congelado no es un monitor atascado.

Modelo de datos (SQLite, esquema v3)

Las migraciones son aditivas y se ejecutan al arrancar (Store._migrate).

Campos de reconstrucción tras un fallo

Estos campos de la fila event bastan para reconstruir el estado completo del evento tras cualquier caída; todo lo demás es derivado:

Con eso más el reloj de pared, resume_after_restart() puede seguir vigilando, reanudar una ventana de gracia, congelar la clasificación o reenviar anuncios perdidos sin adivinar nada. Los mismos invariantes los ejercitan las pruebas de inyección de fallos en tests/test_resilience.py.

Casos límite cubiertos por pruebas

Dos decisiones de política deliberadas que conviene conocer:

• Una caída no hace fallar el evento (el bot no puede demostrar que el canal se vació mientras estaba ciego), pero nadie gana tiempo de clasificación por esa ventana y el hueco se muestra en la salida de progreso y estado.
• Si el canal está vacío en el mismo tick en que caería un hito, gana el fallo: no había nadie presente para reclamar la recompensa.

Pruebas

tests/ replica las capas. Sin red, sin token de Discord y sin pantalla:

pip install -r requirements-dev.txt

./tools/check.sh          # compile + pyflakes + ruff + mypy + pruebas + simulaciones
./tools/check.sh --fast   # lo mismo, sin las simulaciones
python -m pytest          # solo pruebas: no hace falta conexión con Discord

python tools/simulate.py              # imprime cada mensaje de una partida completa de 160 h, offline
python tools/simulate.py --fail-at 40 # …de una partida que muere a las 40 horas

tools/simulate.py conduce el motor real y los renderizadores de mensajes reales sin conexión: es la forma más rápida de revisar textos o verificar un cambio de regla de punta a punta. La configuración de las herramientas vive en pyproject.toml.

Hay un workflow de GitHub Actions ya hecho (pruebas en Python 3.10–3.12, lint y las dos rutas de simulación) en deploy/github-actions-ci.yml: se copia a .github/workflows/ci.yml para activarlo.

Marca. assets/hellbotlogo.png es la obra maestra. Tras cambiarla, ejecuta python tools/make_icon.py para regenerar el icono de ventana, el logotipo de cabecera y el .ico mult tamaño de Windows que usa el ejecutable compilado.