From 236aac7c7fb495eb50e294076ab00ff223f4d1d4 Mon Sep 17 00:00:00 2001 From: sergio Date: Fri, 3 Jul 2026 06:03:48 -0400 Subject: [PATCH] =?UTF-8?q?docs:=20ADR=200009=20c=C3=B3digo=20direccionado?= =?UTF-8?q?=20por=20contenido=20(H3a)=20=E2=80=94=20registrar=20visi=C3=B3?= =?UTF-8?q?n=20Unison?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Design-doc de la idea 3 (SDD 15 §H3): decide NO reescribir la unidad de compilación. Puente barato = procedencia por-símbolo como metadata (extender el parser ELF parse_elf_needed para emitir exports de .dynsym), fuera de hash_inputs — misma disciplina que la evidencia de H1. El grano fino real (función-por-hash) se difiere a H3b sobre wasm, gateado por el determinismo H2. Marca §H3a ✅ en la frontera. Co-Authored-By: Claude Opus 4.8 --- docs/15-frontier-ai-native.md | 10 +-- docs/adr/0009-content-addressed-code.md | 99 +++++++++++++++++++++++++ 2 files changed, 104 insertions(+), 5 deletions(-) create mode 100644 docs/adr/0009-content-addressed-code.md diff --git a/docs/15-frontier-ai-native.md b/docs/15-frontier-ai-native.md index 05b4daef..3d8e6c94 100644 --- a/docs/15-frontier-ai-native.md +++ b/docs/15-frontier-ai-native.md @@ -143,11 +143,11 @@ compilación entera. El valor es real (fin del dependency-hell para la IA) pero proyecto, no una fase. **Qué SÍ hacer ahora (el puente barato hacia la visión):** -- **H3a** — Doc de diseño `docs/adr/00NN-content-addressed-code.md`: qué se ganaría, qué unidad - (¿AST de Rust? ¿un IR propio? ¿wasm por función?), y el punto de contacto realista con lo que - ya existe — la procedencia por-función podría empezar como **metadata** en el `.hammer/recipe.toml` - (qué símbolos exporta un artefacto, ya tenemos el parser ELF `DT_NEEDED` de Fase 6) sin cambiar - la unidad de build. Registrar la visión, no comprometerse a la reescritura. +- **H3a** ✅ — Doc de diseño `docs/adr/0009-content-addressed-code.md` (2026-07-03): registra la + visión Unison y decide **no reescribir la unidad de compilación**. Puente barato = procedencia + por-símbolo como **metadata** (extender `parse_elf_needed`, `query.rs:298`, para emitir exports de + `.dynsym` además de `DT_NEEDED`), fuera de `hash_inputs` (misma disciplina que la evidencia de H1). + El grano fino real (función-por-hash) se difiere a H3b sobre **wasm**, gateado por H2. - **H3b** — (exploratorio, opcional) Un experimento aislado: una base content-addressed de funciones **wasm** (grano: un `.wasm` por función pura de H2), viendo si el modelo "insertar definición, nunca romper" se sostiene sobre el runtime de wawa. Es el subconjunto de Unison diff --git a/docs/adr/0009-content-addressed-code.md b/docs/adr/0009-content-addressed-code.md new file mode 100644 index 00000000..8489905a --- /dev/null +++ b/docs/adr/0009-content-addressed-code.md @@ -0,0 +1,99 @@ +# 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:`) 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.