El hashing de entradas: qué compone el hash de una tarea

Un hash es, antes que una cadena hexadecimal, una teoría: la teoría de qué cosas determinan el resultado de una tarea. Cuando una herramienta de build resume una tarea en una clave de tamaño fijo, afirma algo fuerte —que todo lo que puede alterar la salida está contenido en esa cuenta, y que nada de lo que quedó fuera importa—. Este nivel abre esa cuenta y mira qué entra: los archivos fuente, las dependencias resueltas, las variables de entorno y los flags de invocación. Entender la composición del hash es saber, con exactitud quirúrgica, cuándo dos ejecuciones son “la misma” a ojos de la caché y cuándo no.

Las cuatro familias de entradas

Toda herramienta de caching moderna —Turborepo, Nx, Bazel— construye el hash de una tarea a partir de las mismas cuatro familias de entradas. No son una lista arbitraria: son, en conjunto, todo aquello que puede hacer que el mismo comando produzca una salida distinta. Si algo no cae en ninguna de las cuatro, o no afecta a la salida, o es un agujero por el que se colará un error.

Las dos primeras familias son intuitivas: nadie discute que cambiar el código o subir la versión de una librería deba invalidar el resultado. Las dos últimas son las que la gente olvida, y son justo las que producen los fallos más desconcertantes. Una variable de entorno que la tarea lee pero nadie declaró queda fuera del hash, y entonces dos valores distintos comparten clave; un flag que cambia el modo de compilación pero que la caché no ve produce el mismo síntoma. La disciplina del hashing consiste, en gran medida, en no dejar fuera de la cuenta a las familias tres y cuatro.

De muchos archivos a una sola clave

El hash no se calcula sobre un montón de bytes concatenados a lo bruto. Se construye como un árbol de hashes —una estructura de Merkle—, y esa forma no es un capricho de implementación: es lo que hace el cálculo rápido, incremental y verificable.

El primer paso es hashear cada archivo por separado. Aquí las herramientas hacen una jugada astuta: si el repositorio está en git, muchas reutilizan el hash de objeto que git ya calculó para cada archivo —el blob que identifica su contenido— en lugar de releer y rehashear todo. El índice de git es, en la práctica, una caché de hashes de archivo ya calculada, y apoyarse en ella ahorra el grueso del trabajo.

Con el hash de cada archivo en mano, se combinan los de una misma familia en un hash de familia, y luego los cuatro hashes de familia en el hash final de la tarea. El resultado es una función de agregación por capas:

# Esquema conceptual del calculo, de hojas a raiz
hash_archivos = H(blob_a + blob_b + blob_c ...)
hash_deps     = H(version_resuelta_de_cada_dependencia)
hash_env      = H(nombre=valor de cada variable declarada)
hash_flags    = H(modo + target + opciones + definicion de la tarea)

# La raiz del arbol: el hash de la tarea
hash_tarea = H(hash_archivos + hash_deps + hash_env + hash_flags + hashes_rio_arriba)

La virtud de esta estructura es la incrementalidad. Si cambias un solo archivo, solo su hoja se recomputa; el resto del árbol se reutiliza y únicamente se rehacen los nodos internos que quedan por encima de esa hoja hasta la raíz. Hashear todo el repositorio desde cero en cada corrida sería inviable a escala; el árbol convierte un coste proporcional al tamaño del repo en uno proporcional a lo que cambió.

flowchart TD
f[hash de archivos fuente] --> H[hash de la tarea]
d[hash de dependencias resueltas] --> H
e[hash de variables de entorno] --> H
fl[hash de flags e invocacion] --> H
up[hashes de tareas rio arriba] --> H
H --> key[clave direccionable por contenido]
style H fill:#f9e2af,color:#11111b
style key fill:#a6e3a1,color:#11111b

Falta una quinta rama en el árbol que no es una familia de entradas propias, pero sí entra en el hash: los hashes de las tareas de las que esta depende. En un monorepo, si tu build depende del build de una librería interna, el hash de esa librería se incorpora al tuyo. Así un cambio río arriba se propaga río abajo sin que tengas que declararlo: reescribe el hash de la dependencia, y ese cambio sube por el árbol hasta reescribir el tuyo.

El hash es del contenido, no de la máquina

La propiedad que lo hace todo posible es esta: el hash depende solo del contenido de las entradas, no de la máquina, ni del usuario, ni del reloj. Dos ordenadores que parten del mismo código, resuelven el mismo lockfile y declaran las mismas variables computan, bit a bit, el mismo hash. No existe “mi hash” frente a “tu hash”.

Esa es exactamente la propiedad —el direccionamiento por contenido— que permite que una caché sea compartida. Si el hash fuera local a la máquina, cada ordenador tendría su propia memoria y nada podría reutilizarse entre ellos. Como el hash es una propiedad del contenido, sirve de dirección universal: cualquier máquina que produzca ese contenido calcula esa dirección y puede preguntar por ella a un almacén común. La caché remota que viste en niveles anteriores no es más que esta idea llevada a la red.

De aquí se sigue una exigencia que gobierna todo lo demás: para que “mismo hash implica mismo resultado” sea cierto, nada que afecte a la salida puede quedar fuera del hash, y nada dentro del hash puede depender de algo que no sea contenido. Un reloj, una ruta absoluta o un identificador de máquina que se cuele en las entradas rompe el direccionamiento, porque hace que el mismo contenido produzca hashes distintos en sitios distintos. El hash sano es una fotografía del contenido y de nada más.

Por qué los flags son una entrada

De las cuatro familias, la de los flags es la que más cuesta aceptar como entrada de primera clase, y conviene defenderla. Un build de producción y uno de desarrollo pueden partir de los mismos archivos, las mismas dependencias y las mismas variables, y aun así producir artefactos completamente distintos: uno minificado y sin mapas de depuración, otro legible y con ellos. La única diferencia está en cómo se invocó la tarea —el modo, el target, las opciones—. Si esa diferencia no entrara en el hash, ambos builds compartirían clave, y pedir producción te devolvería, feliz y en silencio, el artefacto de desarrollo.

{
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "inputs": ["src/**", "tsconfig.json"],
      "env": ["NODE_ENV", "BUILD_TARGET"],
      "outputs": ["dist/**"]
    }
  }
}

Por eso la definición misma de la tarea —lo que ves arriba— forma parte del hash: cambiar el dependsOn, los inputs declarados o las opciones de compilación reescribe la clave, porque cambia la función que se está ejecutando. La tarea no es solo su código; es su código más la manera exacta en que se lo invoca. Tratar los flags como entrada es reconocer que compilar es aplicar una función a unos argumentos, y que los flags son argumentos tanto como los archivos.