# SDD 33 — Versionar takana: cómo se llama una versión, qué reloj mira qué, y qué se cambia solo

> **Estado: PROPUESTA, con la primera pieza IMPLEMENTADA y medida** (2026-09-23):
> `scripts/fuentes/upstream-vigia.py`. Lo demás está decidido y no construido, y se dice cuál es
> cuál.

## 0. La pregunta

> *¿cómo ir versionando esto? hay las actualizaciones desde los orígenes que hay que adaptar las
> recetas, por ejemplo ya está kernel 7.3. y lo que voy desarrollando de tawasuyu que avanza rápido.*

Son **tres** preguntas y conviene no mezclarlas, porque cada una se contesta distinto:

1. **Cómo se LLAMA una versión** de takana — hoy no se llama de ninguna manera.
2. **Quién mira qué se movió río arriba**, y cada cuánto.
3. **Qué se puede cambiar solo** y qué no. Ésta es la única con filo.

## 1. Una versión ya existe, y no es un número

La identidad real de una imagen **ya está**: es el hash de la clausura de su perfil. No se puede
falsificar, no depende de quién la armó y dos imágenes con el mismo hash son la misma imagen. Eso es
mejor que cualquier número, y es lo que el sistema usa para todo.

Lo que falta es un nombre que una persona pueda decir en voz alta. Propuesta:

| | |
|---|---|
| **identidad** | `b3:<hash de la clausura del perfil>` — exacta, la que verifica |
| **nombre** | `takana AÑO.MES[.n]` — `takana 2026.09`, y `2026.09.2` si hay más de una en el mes |
| **dónde vive** | en la imagen (`/etc/os-release`), en el nombre del fichero publicado, y lo imprime el instalador antes de tocar el disco |

⚠ **El nombre NO es la versión: es una etiqueta sobre ella.** Un fichero llamado
`takana-2026.09-mirada.sh` tiene que decir de qué clausura salió, porque el día que alguien
reconstruya para comprobar, lo que compara es el hash. Publicar sólo el nombre es la forma barata de
que el sitio empiece a mentir — que es lo que ya pasó con un sha256 pegado a mano en la página.

## 2. Tres relojes, no dos, y ya hay uno andando

| reloj | cada | qué hace | estado |
|---|---|---|---|
| **cosecha** | 30 min | trae del worker lo que se selló, siembra recetas, regenera el estado y commitea | **anda** (`scripts/farm/cosecha-cron.sh`) |
| **río arriba** | 1 día | pregunta a cada fuente si hay algo más nuevo que el pin, y deja un informe | **la pieza implementada hoy** |
| **medios** | cuando el cierre cambie | rearma imágenes e instaladores y publica | **falta** |

### 2.1 Río arriba — `scripts/fuentes/upstream-vigia.py`

Pregunta lo que `fuentes-vigia.sh` no pregunta. Aquél mira si la fuente **sigue viva**; éste mira si
hay **algo más nuevo que lo que tenemos clavado**. Se confunden, y son las dos mitades: una fuente
viva puede llevar dos años sin tocarse, y una que se movió ayer puede desaparecer mañana.

Medido el 2026-09-23, primera corrida completa:

```
660 recetas con repo git · 17 s
462 con un tag más nuevo que el pin
606 con la rama movida desde el pin
625 recetas pinean un TARBALL y esta vigía no las mira
```

**Por qué sólo git, y por qué eso ya es la mitad.** `git ls-remote` funciona contra cualquier
servidor sin API, sin token y sin clonar — es lo mismo que ya hace `takana pin`. Con eso se cubren
las 660 que pinean `repo` + `commit`. Un tarball no tiene equivalente general: saber si hay una
versión nueva pide una pista por receta (dónde mirar, con qué patrón), y eso es su propia unidad de
trabajo. **Se cuentan y se dicen**, no se adivinan: 625 recetas fuera del radar es un dato, no un
silencio.

⚠ **Sale 0 siempre.** Un guardián que falla porque upstream sacó una versión nueva grita todos los
días y en una semana nadie lo mira ([[guardianes-el-ruido-los-mata]]).

## 3. Qué se cambia solo — la única pregunta con filo

> **Se automatiza el pin de lo NUESTRO. No se automatiza el de nadie más.**

### 3.1 tawasuyu: sí, y de a un repo entero

Son **37 recetas sobre el MISMO monorepo**, y ahí está la trampa: bumpear 37 pins de a uno da una
imagen con 37 commits distintos del mismo árbol — mezcla de versiones que nunca existió junta y que
nadie probó. El bump tiene que ser **atómico por repositorio**: todas las recetas que comparten
`repo` saltan al mismo commit, o no salta ninguna.

Es defendible automatizarlo porque es código propio, la granja lo reconstruye y los guardianes ven
la rotura. Lo que **no** se automatiza ni ahí es publicar: un bump que compila no es un bump que
arranca.

### 3.2 Terceros: no, y el kernel 7.3 es el ejemplo

Una versión nueva de upstream puede cambiar el sistema de build, las banderas, las dependencias y el
resultado. Aplicarla sola es cambiar la receta sin leerla.

El kernel lo muestra entero: pasar de 6.16 a 7.3 no es cambiar un número. Toca el contrato de
kconfig (SDD 22), las opciones que nuestras imágenes exigen (`CONFIG_KEXEC_FILE`, el EFI-stub, el
`CONFIG_CMDLINE` horneado del que depende el arranque del USB), los drivers de las máquinas que ya
validamos, y las tasas del SDD 25. **Es una unidad de trabajo, no una línea de cron.**

⇒ Para terceros la vigía **propone**: deja el informe, y quien decide aplica con `takana pin` y una
construcción. Proponer y aplicar son verbos distintos y conviene que también sean comandos distintos.

## 4. Cuándo rearmar los medios: por el CIERRE, no por el calendario

Un cron semanal que rearma las imágenes gasta horas de worker para producir, casi siempre, **los
mismos bytes**. El disparador correcto no es el tiempo: es que la clausura del perfil haya cambiado.

```
por cada perfil publicado:
    h = hash de la clausura del perfil            (barato: `takana hash`, sin construir)
    si h ≠ el hash de la imagen publicada:
        rearmar, probar con los tres arneses, publicar
```

Y **publicar es lo último**, después de los arneses, nunca antes: hoy son 25 comprobaciones del
banco, 13 del salto y 13 del USB, y las tres corren sin intervención.

⚠ **El paso que falta y hay que escribir: la imagen publicada tiene que declarar de qué clausura
salió.** Sin eso, la comparación de arriba no se puede hacer y el cron vuelve a ser un calendario.

## 5. Lo que este documento NO decide

- **La pista por receta para los tarballs** (625). Hace falta un campo tipo `[source.upstream]` con
  dónde mirar y qué patrón; es su propia unidad.
- **Si el nombre lleva mes o semana.** Depende de cada cuánto se publique de verdad, y eso todavía
  no se sabe porque hoy se publica a mano.
- **Firmar lo publicado.** Los `.sha256` de al lado comprueban la descarga, no la procedencia. El
  repo de paquetes ya tiene firma (ADR 0014); las imágenes no, y son lo que más se copia.