takana/docs/adr/0009-content-addressed-code.md

# ADR 0009 — Código direccionado por contenido (estilo Unison): registrar la visión, no reescribir la unidad

- **Estado:** propuesta (design-doc — registra una dirección, no compromete una reescritura)
- **Fecha:** 2026-07-03
- **Frontera:** SDD 15 §H3 (idea 3). Depende conceptualmente de [ADR pendiente H2] y del
  determinismo wasm auditado en H2a (`tawasuyu/03_ukupacha/wawa/SDD-determinismo.md`).

## Contexto

takana y wawa **ya** direccionan por contenido, pero *cosas distintas*:

- **takana** hashea el **artefacto compilado** y la **receta**. La identidad de un artefacto es
  `ArtifactHash` sobre las entradas canónicas de la receta (`Recipe::hash_inputs`,
  `crates/hammer-core/src/recipe.rs:370`): `source_id` (commit git o sha256 del tarball),
  compilador, target, link, `zig_version`, contenido de los patches, flags, overrides de fases.
  Grano **grueso**, lenguaje-**agnóstico**: encaja con "recetas sobre fuente upstream".
- **wawa** hashea el **módulo wasm** y el **objeto** del grafo/almacén. Grano de módulo/objeto.

La **idea 3** (Unison) empuja al límite: direccionar **funciones por el hash de su AST**. En
Unison, el código no vive en archivos sino en una base content-addressed donde cada definición
ES su hash; renombrar es metadata, actualizar es insertar una definición nueva (la vieja no se
rompe: quien la referenciaba sigue apuntando a su hash). El sueño para un agente de IA: **no
editar archivos que se rompen entre sí**, sino insertar definiciones en un espacio donde
*nada se rompe por renombrar o actualizar*. Paquete de takana, módulo wasm de wawa y función
de código **colapsarían en un solo espacio de nombres: el hash**.

## Decisión

**Registrar la visión y NO reescribir la unidad de compilación.** Concretamente:

1. **No** colapsar ahora artefacto/módulo/función en un solo tipo. takana sigue con grano de
   artefacto; wawa con grano de módulo. La identidad content-addressed de cada uno queda intacta.
2. **Sí** construir el *puente barato*: **procedencia por-símbolo como metadata**, derivada de lo
   que ya sabemos leer, SIN tocar `hash_inputs` ni la unidad de build. takana ya tiene un parser
   ELF hand-rolled (`parse_elf_needed`, `crates/hammer-core/src/query.rs:298`) que extrae
   `DT_NEEDED` (las libs dinámicas que un binario necesita) para la query `depends:`. Extenderlo
   para emitir también los **símbolos exportados** (`.dynsym`) da, por artefacto, "qué provee y
   qué necesita" — un grafo de símbolos content-addressed **descriptivo**, no normativo: es
   metadata anexa a la receta/artefacto, no entra al hash de identidad (misma disciplina que el
   bloque `evidence` de H1: describe, no identifica).
3. **Diferir** el grano fino real (función-por-hash) a **H3b**, un experimento aislado sobre
   **wasm** (un `.wasm` por función pura del subconjunto determinista de H2), que es el
   subconjunto de Unison que nuestro stack *ya* podría sostener (wasm + BLAKE3 + determinismo
   H2a) **sin un lenguaje nuevo**. H3b es exploratorio y está gateado por H2 en verde.

## Razones

- **Es otro modelo de datos, no una extensión.** takana content-addressa el artefacto compilado
  (grano grueso, lenguaje-agnóstico); Unison el AST de cada función (grano fino, exige un
  lenguaje y toolchain propios). Colapsarlos pide reescribir la unidad de compilación entera —
  eso es un proyecto, no una fase. El ADR lo dice para no fingir que es una feature incremental.
- **El valor es real pero el costo es un proyecto.** El fin del *dependency-hell* para un agente
  (insertar una definición nunca rompe a quien la usa) es exactamente lo que haría al bucle
  agéntico de SDD 08 mucho más seguro. Pero comprometerse hoy a la reescritura del build sería
  cambiar los cimientos por una apuesta no probada. Design-doc primero.
- **El puente barato entrega valor sin apostar.** La procedencia por-símbolo (paso 2) es útil
  ya: alimenta queries "¿qué artefacto exporta `foo`?", detección de colisiones de símbolos entre
  paquetes, y una primera forma de "referencia por contenido" (un consumidor puede pinnear no el
  paquete sino el *símbolo+hash* que usa). Todo reusando el parser ELF existente.
- **Respeta la disciplina de identidad de takana.** Nada de esto mueve `ArtifactHash`: el
  baseline de reproducibilidad (of_tree 9adefb82 / rust 7fa6cb4e) no se toca. La procedencia es
  metadata, como la evidencia de H1.

## Consecuencias

- **Ahora (barato, sin apuesta) — IMPLEMENTADO (2026-07-03):** `parse_elf_needed` → `parse_elf_info`
  (exports de `.dynsym` además de `DT_NEEDED`), expuesto como query **`exports:<artefacto>`**
  (`crates/hammer-core/src/query.rs`). Validado end-to-end: 2873 símbolos extraídos de
  `/lib/libc.so.6`. Fluye por el bus (`query expr`) sin cambios. Cero cambio en el build ni en
  `hash_inputs`. Pendiente opcional: emitirlo como sidecar de metadata junto al artefacto sellado.
- **Diferido (condicionado a verdes):** H3b (base content-addressed de funciones **wasm**), sólo
  si H2b demuestra que el cómputo puro memoiza byte-idéntico. Si H3b se sostiene, *entonces* se
  reabre la pregunta de colapsar los tres espacios — con evidencia, no con fe.
- **La frontera de confianza no se mueve.** Igual que en H1/H2c: la IA no se auto-promueve;
  un símbolo/función ajena direccionada por hash se **verifica reproduciéndola** en el primer uso
  dudoso (modelo de SDD 09 aplicado al grano fino). No se confía en el resultado ajeno; se confía
  en poder recomputarlo.
- **No se promete** "una distro donde paquete = función = proceso" hasta que H3b lo demuestre
  sobre wasm. Es la idea más disruptiva y la menos madura del SDD 15; se trata como tal.

## Alternativas consideradas

1. **Adoptar Unison/su runtime tal cual.** Rechazada: arrastra un lenguaje y toolchain propios;
   takana es lenguaje-agnóstico por diseño (ADR 0002/0003, recetas sobre fuente upstream). Sería
   cambiar la tesis del proyecto.
2. **Reescribir takana para content-addressar AST de Rust.** Rechazada ahora: acopla la identidad
   del artefacto a un lenguaje concreto y a un parser de AST frágil; rompe "recetas sobre fuente
   upstream en cualquier lenguaje". Reevaluable sólo si H3b da señal fuerte.
3. **No registrar nada (esperar).** Rechazada: la visión orienta decisiones de diseño cercanas
   (p.ej. mantener la procedencia como metadata fuera del hash desde ya deja la puerta abierta sin
   costo). Registrarla barato es mejor que redescubrirla.

## Referencias

- SDD 15 §H3 (`docs/15-frontier-ai-native.md`) — la idea 3 y por qué es design-doc.
- H2a — determinismo wasm (`tawasuyu/03_ukupacha/wawa/SDD-determinismo.md`): el grano fino wasm
  de H3b depende de este verde.
- `Recipe::hash_inputs` (`crates/hammer-core/src/recipe.rs:370`) — la identidad que NO se toca.
- `parse_elf_needed` (`crates/hammer-core/src/query.rs:298`) — el parser a extender para la
  procedencia por-símbolo (el puente barato).
- ADR 0002 (alpine-first) / 0003 (zig-cc): la tesis lenguaje-agnóstica que Unison tensiona.