Outputs y su restauración: la respuesta que la caché guarda

Todo el nivel anterior giraba en torno a la clave; ahora toca el valor. Si el hash es la pregunta —qué tarea, con qué entradas—, los outputs son la respuesta que la caché archiva para no tener que volver a deducirla. Y la respuesta es más rica de lo que parece: no basta con guardar los archivos que la tarea produjo, porque una corrida no es solo su artefacto, es también lo que imprimió y cómo terminó. Restaurar bien es reproducir la corrida completa —artefacto, logs y veredicto— con tal fidelidad que quien mira la terminal no distinga un hit de una ejecución real. Y ahí, en esa exigencia de fidelidad total, es donde una declaración descuidada de outputs se vuelve peligrosa.

Qué se guarda: artefacto, logs y veredicto

Una entrada de caché es un par: una clave —el hash— y un valor. El error común es imaginar que el valor son solo los archivos generados. Es más que eso. Una tarea de build no produce únicamente un directorio dist; produce también un flujo de salida por la terminal y termina con un código de salida que dicta si tuvo éxito o falló. Los tres forman parte de lo que hay que guardar, porque los tres forman parte de “lo que pasó” cuando la tarea corrió.

Junto a esos tres componentes, la entrada suele cargar algo de metadato: la propia clave del hash bajo la que se guarda, la duración de la corrida original y a veces un pequeño manifiesto de qué archivos contiene. Ese metadato no es decorativo: es lo que permite a la herramienta decirte “restaurado de caché, ahorrados 42 segundos” y lo que sostiene las métricas de tiempo ahorrado que justifican tener la caché. El artefacto es el cuerpo de la entrada; el metadato es su etiqueta.

Guardar el código de salida tiene una consecuencia sutil: la caché es, por norma, un archivo de éxitos. La mayoría de las herramientas solo almacenan corridas que terminaron en cero, porque un fallo depende con frecuencia de factores efímeros —una red caída, un recurso ocupado— que no forman parte del hash y que, por tanto, no deben quedar congelados bajo una clave. Reutilizar un fallo sería peor que recomputarlo.

Tareas sin artefacto: cuando el output son los logs

No toda tarea produce archivos, y esas son el mejor recordatorio de que la entrada de caché es más que su artefacto. Un lint o un test que solo verifica —que no emite un dist— declara una lista de outputs vacía, y aun así se cachea con todo el sentido: lo que se guarda es su flujo de logs y su código de salida. Un hit sobre ese lint no restaura ningún archivo, pero reproduce sus advertencias y devuelve su cero, que era justo su producto: la afirmación, reutilizable, de que ese estado de fuentes pasa la verificación. Aquí se ve con nitidez que la caché no cachea archivos, sino el resultado observable de una tarea, tenga forma de artefacto o de veredicto.

Cómo se restaura una corrida

En un miss, el ciclo es de captura: la herramienta ejecuta la tarea, recoge los archivos que caen bajo los patrones de outputs, captura el flujo de logs y anota el código de salida, y empaqueta los tres bajo la clave del hash —en disco local y, si hay caché remota, subiéndolos al almacén compartido—. En un hit, el ciclo se invierte: recupera la entrada por su clave, copia los artefactos de vuelta a sus rutas declaradas, reproduce los logs por la terminal y devuelve el código de salida guardado.

flowchart TD
M[Cache miss] --> R[Ejecuta la tarea]
R --> Cap[Captura artefactos, logs y codigo de salida]
Cap --> S[Almacena bajo la clave del hash]
H[Cache hit] --> F[Recupera la entrada por su clave]
F --> Res[Restaura artefactos en sus rutas]
Res --> Rep[Reproduce los logs y devuelve el codigo]
style H fill:#a6e3a1,color:#11111b
style M fill:#f9e2af,color:#11111b

La reproducción de los logs merece defenderse, porque parece un lujo y es una necesidad. El principio rector de una buena caché es la transparencia: un hit debe ser indistinguible de una ejecución real salvo por su velocidad. Si al reutilizar una tarea desaparecieran los avisos, las advertencias del compilador o los mensajes que tu pipeline inspecciona más adelante, la caché habría cambiado el comportamiento observable del sistema, y eso rompe el contrato de que reutilizar es equivalente a recomputar. Por eso las herramientas capturan la salida palabra por palabra y la re-emiten en el hit —el “replay” instantáneo—: para que ni tú ni el resto del pipeline noten la diferencia.

En una caché remota el mismo ciclo cruza la red. El artefacto se comprime en un tarball, se sube al almacén de objetos con la clave del hash como nombre, y en un hit remoto se descarga y se descomprime en su sitio. Que el envío atraviese red es la razón de que el tamaño de lo que declaras como output importe: cada archivo de más es ancho de banda y almacenamiento de más, multiplicado por cada corrida de cada máquina del equipo.

Modos de restauración y el invariante que los une

No todos los hits restauran desde el mismo sitio ni con las mismas reglas. Un hit local copia los artefactos desde el directorio de caché de la máquina; un hit remoto los descarga y descomprime. En CI es común configurar la caché remota en modo de solo lectura —lee para acelerar pero no escribe—, o al revés, de solo escritura para alimentar a los demás sin consumir. Y hay una sutileza de eficiencia: si los artefactos ya están en disco y coinciden con los guardados, algunas herramientas se ahorran la copia. Debajo de toda esa variedad late un único invariante que jamás puede romperse: sea cual sea el modo, el estado final en disco tras un hit tiene que ser idéntico al que dejaría una ejecución real. El modo es una decisión de rendimiento; la fidelidad del resultado, no.

Outputs incompletos igual a caché corrupta

Aquí está el filo del cuchillo. La declaración de outputs sufre la misma asimetría que la de inputs, pero con las consecuencias volcadas al otro lado. Declarar de más es un pecado de rendimiento: guardas y transfieres archivos inútiles, la caché engorda y los hits se vuelven más lentos de lo necesario. Molesto, pero honesto. Declarar de menos es un pecado de corrección, y es silencioso y devastador.

{
  "tasks": {
    "build": {
      "outputs": ["dist/**", "types/**"]
    }
  }
}

Imagina que esa tarea genera de verdad dist, types y un manifest.json en la raíz, pero solo declaraste los dos primeros. La primera corrida es un miss: la tarea se ejecuta entera, escribe los tres, y todo funciona porque el manifest.json está ahí de la ejecución real. La caché, en cambio, solo guardó dist y types. El desastre llega en el primer hit en un entorno limpio —otra máquina, CI, tras borrar artefactos—: la caché restaura dist y types, reproduce los logs de éxito, devuelve un código cero triunfal… y el manifest.json no existe, porque nunca se guardó. La tarea “tuvo éxito” desde la caché y dejó un artefacto roto.

El coste simétrico: declarar de más

Si declarar de menos corrompe, declarar de más engorda. La asimetría no significa que puedas pecar de generoso sin consecuencias: incluir en los outputs archivos que la tarea no necesita restaurar tiene un precio real, solo que se paga en rendimiento y no en corrección. Cada archivo sobrante infla el tarball que se comprime, sube y baja en cada hit remoto, ocupa espacio en el almacén compartido y ralentiza justo la operación que la caché existía para acelerar. Un dist que arrastra por error una carpeta de artefactos intermedios o un directorio de dependencias puede convertir un hit que debía durar milisegundos en una descarga de cientos de megabytes.

El punto dulce, entonces, no es “declara todo por si acaso” ni “declara lo mínimo para ahorrar”, sino declarar exactamente lo que la tarea produce y algún consumidor río abajo necesita: ni un archivo de menos, que rompería la restauración, ni uno de más, que la encarecería. A diferencia de los inputs —donde ante la duda conviene incluir, porque el error barato es el falso miss—, en los outputs los dos errores tienen dientes, y el criterio correcto es la exhaustividad ajustada: todo lo que la tarea genera y se vaya a usar, y nada de lo que solo fue un paso intermedio.