sergioandClaude Opus 4.8
8bf1623044
Arranque del proyecto hammer (distro AI-nativa: laboratorio funcional en el sótano, terminal mutable clásica arriba, integración de IA programadora). - Workspace Rust (compila, tests verdes): hammer-core, hammer-build, hammer-cli (bin `hammer`), hammerd. - SDDs 00-10 + 6 ADRs en docs/ con toda la arquitectura. - Esqueletos navegables mapeados a las fases del roadmap; Fase 0/1 listas para implementar el sandbox real. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
114 lines
5.6 KiB
Markdown
114 lines
5.6 KiB
Markdown
# SDD 08 — Integración de la IA
|
|
|
|
La IA es un **artesano hiperveloz en el taller**; el humano es **el dueño que decide si el
|
|
mueble entra a la casa o se va a la basura.** Esta sección define el bucle agéntico, sus
|
|
garantías de seguridad, y cómo una intención en lenguaje natural se vuelve un cambio real.
|
|
|
|
## 1. La terminal como runtime de la IA
|
|
|
|
La IA no es un chat en una ventana que te dice qué teclear. Opera directamente sobre el sistema
|
|
a través del **bus de agente** ([SDD 07](07-agent-bus.md)) y de un **overlay**
|
|
([SDD 04](04-overlay.md)). Su entorno de trabajo es el sistema real, con red de seguridad.
|
|
|
|
## 2. El bucle agéntico
|
|
|
|
```
|
|
intención (NL)
|
|
│ "que grep ignore binarios por defecto y use regex Perl,
|
|
│ y que la red use IP estática 192.168.1.100"
|
|
▼
|
|
┌─────────────┐
|
|
│ PLAN │ la IA traduce la intención a un .swm: qué herramienta,
|
|
│ │ qué patch de fuente, qué flags, qué config editar
|
|
└──────┬──────┘
|
|
▼
|
|
┌─────────────┐
|
|
│ BUILD │ COMPILE por el bus → el lab clona repo@commit, aplica patch,
|
|
│ (lab) │ compila estático con zig cc → artifact_hash
|
|
└──────┬──────┘
|
|
▼
|
|
┌─────────────┐
|
|
│ TRY │ hammer try → overlay temporal; INJECT del artefacto y de las
|
|
│ (overlay) │ ediciones de config en la capa. El sistema real intacto.
|
|
└──────┬──────┘
|
|
▼
|
|
┌─────────────┐
|
|
│ VERIFY │ corre el test harness; escucha BUILD_FAILED / CRASHED por el bus.
|
|
│ │ si falla → corrige fuente → recompila (vuelve a BUILD).
|
|
└──────┬──────┘
|
|
▼
|
|
┌─────────────┐
|
|
│ PROPOSE │ la IA avisa: "listo, probé esto, aquí el diff y el resultado".
|
|
│ │ presenta el .swm y la evidencia.
|
|
└──────┬──────┘
|
|
▼
|
|
┌─────────────┐
|
|
│ HUMANO │ tú decides: hammer commit (promueve + diario) o hammer discard.
|
|
│ decide │ La IA NUNCA promueve al FHS real por su cuenta (ver §4).
|
|
└─────────────┘
|
|
```
|
|
|
|
## 3. Por qué esta arquitectura se presta (y otras no)
|
|
|
|
- **Determinismo del lab** → la IA puede recompilar y volver atrás sin dramas; el resultado es
|
|
predecible.
|
|
- **Texto plano + binarios atómicos** → la IA lee/escribe archivos e inspecciona binarios con
|
|
`readelf`/`objdump`; no parsea bases de datos opacas.
|
|
- **musl legible** → el código C de la libc base es comprensible en el contexto de un LLM
|
|
(glibc es un laberinto de macros).
|
|
- **Enlazado estático** → una herramienta mutada corre sin romper enlaces de otros programas.
|
|
- **Mutabilidad + overlay** → agencia real con red de seguridad; sin rollbacks pesados.
|
|
|
|
En distros inmutables/declarativas, la IA tendría que lidiar con generadores de config y
|
|
políticas read-only; en tradicionales, no tendría provenance. `hammer` mantiene las **tuberías
|
|
expuestas y de baja entropía**, que es justo lo que un agente necesita.
|
|
|
|
## 4. Garantías de seguridad (no negociables)
|
|
|
|
1. **La IA trabaja en overlay por defecto.** Sin capacidad `inject-real`, no puede tocar el
|
|
FHS base. El flujo es siempre overlay → `commit` humano.
|
|
2. **Capacidades mínimas y explícitas.** El humano concede `query`/`compile`/`inject` por
|
|
separado vía la política del bus ([SDD 07](07-agent-bus.md)).
|
|
3. **Toda acción es reversible y registrada.** `discard` revierte el overlay; el `commit`
|
|
entra al diario firmado ([SDD 05](05-journal.md)).
|
|
4. **Recetas, no binarios.** La IA produce `.swm` (fuente + flags + config), no binarios
|
|
opacos. Lo que comparte es verificable por terceros ([SDD 06](06-swm-format.md)).
|
|
5. **El humano tiene la última palabra.** Ningún cambio se vuelve permanente sin `commit`.
|
|
|
|
## 5. De la intención al `.swm`: el rol del modelo
|
|
|
|
El traductor intención→`.swm` es un LLM. Detalles de modelo/API (Claude, herramientas, prompts)
|
|
se documentarán aparte cuando se implemente la Fase 6; aquí sólo fijamos el contrato:
|
|
|
|
- **Entrada:** intención en NL + contexto del sistema (qué herramientas hay, qué pins, estado
|
|
de servicios — todo consultable por `QUERY`).
|
|
- **Salida:** un `.swm` válido ([SDD 06](06-swm-format.md)) + un plan de verificación.
|
|
- **El modelo no ejecuta nada directamente:** emite comandos por el bus, que `hammerd` valida
|
|
contra las capacidades concedidas.
|
|
|
|
## 6. Lenguaje de consulta/transformación (visión, Fase posterior)
|
|
|
|
Para que la IA refiera partes del sistema sin rutas absolutas frágiles, un mini-lenguaje de
|
|
consulta sobre el grafo del sistema:
|
|
|
|
```
|
|
find /service/web -where "depends_on(libssl)" -> replace_with my_tls
|
|
```
|
|
|
|
El daemon traduce esa consulta estructurada a acciones reales del bus. La terminal sigue siendo
|
|
el lugar de validación final. Esto es visión, no Fase 0 — se diseñará cuando el bucle básico
|
|
esté probado.
|
|
|
|
## 7. Interfaz
|
|
|
|
```rust
|
|
// cliente del bus (puede vivir en un crate aparte hammer-agent en Fase 6)
|
|
pub trait AgentClient {
|
|
fn hello(&mut self) -> Result<Caps>;
|
|
fn compile(&mut self, recipe: &Recipe) -> Result<ArtifactHash>;
|
|
fn inject(&mut self, h: &ArtifactHash, target: &Path, overlay: OverlayId) -> Result<()>;
|
|
fn query(&mut self, q: Query) -> Result<QueryResult>;
|
|
fn events(&mut self) -> impl Iterator<Item = BusEvent>;
|
|
}
|
|
```
|