sergio/takana

> Una distribución Linux construida con un laboratorio funcional y hermético en el > sótano, y una terminal mutable, clásica y anárquica en el piso de arriba — diseñada > desde el suelo para que una IA programadora entienda, modifique y co…

Clonar por HTTPS, con el git de siempre

⎇ main docs/adr/0006-pinned-commits.md Markdown · 38 líneas · 1.6 KB Historia crudo

takana etapa 5b: los 59 docs de diseño, runbooks y ADR 97ceb7241 · Sergio · hace 1 mes

1# ADR 0006 — Commits fijados, no `HEAD` vivo
2
3- **Estado:** aceptada
4- **Fecha:** 2026-06-06
5
6## Contexto
7
8La idea original habla de "repositorios vivos" apuntando al `HEAD` de los upstreams. Romántico,
9pero `HEAD` se rompe a diario y destruye el determinismo que justifica todo el laboratorio
10funcional. Sin entrada estable no hay hash estable, no hay caché fiable, y no hay `.swm`
11verificable.
12
13## Decisión
14
15El lab compila **siempre contra commits fijados** (un lockfile, `pins.toml`). "Repositorio
16vivo" significa **rastreo automatizado del upstream con snapshots fijados**, no `HEAD` ciego.
17
18## Razones
19
20- **Reproducibilidad:** entrada idéntica ⇒ hash idéntico ⇒ salida idéntica
21  ([SDD 02](../02-build-lab.md), [SDD 09](../09-trust-model.md)).
22- **Avance ordenado del grafo:** al subir un pin, sólo cambian ese nodo y sus dependientes;
23  sabes exactamente qué commit causó qué fallo.
24- **`.swm` verificable:** dos máquinas con el mismo pin+patch producen el mismo binario; eso es
25  lo que permite "verificar, no confiar".
26
27## Mecanismo de "vivo"
28
29- `pins.toml` mapea `nombre → commit` por upstream.
30- `takana update [<pkg>]` consulta el upstream, propone subir el pin al nuevo commit, y
31  reconstruye sólo lo afectado. El humano (o la IA) decide cuándo avanzar.
32- Análogo al `flake.lock` de Nix, pero imperativo y bajo tu control.
33
34## Consecuencias
35
36- No hay sorpresas por `HEAD` cambiando bajo tus pies.
37- Mantener los pins al día es una acción explícita (deseable: lo controlas tú/la IA).
38- El pin (commit) forma parte del `artifact_hash`; cambiarlo invalida la caché de ese nodo.

0006-pinned-commits.md

ADR 0006 — Commits fijados, no `HEAD` vivo

Estado: aceptada
Fecha: 2026-06-06

Contexto

La idea original habla de "repositorios vivos" apuntando al HEAD de los upstreams. Romántico, pero HEAD se rompe a diario y destruye el determinismo que justifica todo el laboratorio funcional. Sin entrada estable no hay hash estable, no hay caché fiable, y no hay .swm verificable.

Decisión

El lab compila siempre contra commits fijados (un lockfile, pins.toml). "Repositorio vivo" significa rastreo automatizado del upstream con snapshots fijados, no HEAD ciego.

Razones

Reproducibilidad: entrada idéntica ⇒ hash idéntico ⇒ salida idéntica (SDD 02, SDD 09).
Avance ordenado del grafo: al subir un pin, sólo cambian ese nodo y sus dependientes; sabes exactamente qué commit causó qué fallo.
.swm verificable: dos máquinas con el mismo pin+patch producen el mismo binario; eso es lo que permite "verificar, no confiar".

Mecanismo de "vivo"

pins.toml mapea nombre → commit por upstream.
takana update [<pkg>] consulta el upstream, propone subir el pin al nuevo commit, y reconstruye sólo lo afectado. El humano (o la IA) decide cuándo avanzar.
Análogo al flake.lock de Nix, pero imperativo y bajo tu control.

Consecuencias

No hay sorpresas por HEAD cambiando bajo tus pies.
Mantener los pins al día es una acción explícita (deseable: lo controlas tú/la IA).
El pin (commit) forma parte del artifact_hash; cambiarlo invalida la caché de ese nodo.