hammer/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

hammer y wawa ya direccionan por contenido, pero cosas distintas:

• hammer 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 hammer, 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. hammer 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. hammer 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. hammer 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 hammer. 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): cuando haya rato, extender parse_elf_needed → parse_elf_symbols (exports de .dynsym además de DT_NEEDED) y exponerlo como query (exports:<artefacto>) y, opcionalmente, como sidecar de metadata junto al .hammer/recipe.toml. Cero cambio en el build.
• 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; hammer es lenguaje-agnóstico por diseño (ADR 0002/0003, recetas sobre fuente upstream). Sería cambiar la tesis del proyecto.
2. Reescribir hammer 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.