1# SDD 08 — Integración de la IA
2
3La IA es un **artesano hiperveloz en el taller**; el humano es **el dueño que decide si el
4mueble entra a la casa o se va a la basura.** Esta sección define el bucle agéntico, sus
5garantías de seguridad, y cómo una intención en lenguaje natural se vuelve un cambio real.
6
7## 1. La terminal como runtime de la IA
8
9La IA no es un chat en una ventana que te dice qué teclear. Opera directamente sobre el sistema
10a través del **bus de agente** ([SDD 07](07-agent-bus.md)) y de un **overlay**
11([SDD 04](04-overlay.md)). Su entorno de trabajo es el sistema real, con red de seguridad.
12
13## 2. El bucle agéntico
14
15```
16   intención (NL)
17        │  "que grep ignore binarios por defecto y use regex Perl,
18        │   y que la red use IP estática 192.168.1.100"
19        ▼
20   ┌─────────────┐
21   │  PLAN        │  la IA traduce la intención a un .swm: qué herramienta,
22   │              │  qué patch de fuente, qué flags, qué config editar
23   └──────┬──────┘
24          ▼
25   ┌─────────────┐
26   │  BUILD       │  COMPILE por el bus → el lab clona repo@commit, aplica patch,
27   │  (lab)       │  compila estático con zig cc → artifact_hash
28   └──────┬──────┘
29          ▼
30   ┌─────────────┐
31   │  TRY         │  hammer try → overlay temporal; INJECT del artefacto y de las
32   │  (overlay)   │  ediciones de config en la capa. El sistema real intacto.
33   └──────┬──────┘
34          ▼
35   ┌─────────────┐
36   │  VERIFY      │  corre el test harness; escucha BUILD_FAILED / CRASHED por el bus.
37   │              │  si falla → corrige fuente → recompila (vuelve a BUILD).
38   └──────┬──────┘
39          ▼
40   ┌─────────────┐
41   │  PROPOSE     │  la IA avisa: "listo, probé esto, aquí el diff y el resultado".
42   │              │  presenta el .swm y la evidencia.
43   └──────┬──────┘
44          ▼
45   ┌─────────────┐
46   │  HUMANO      │  tú decides: hammer commit (promueve + diario) o hammer discard.
47   │  decide      │  La IA NUNCA promueve al FHS real por su cuenta (ver §4).
48   └─────────────┘
49```
50
51## 3. Por qué esta arquitectura se presta (y otras no)
52
53- **Determinismo del lab** → la IA puede recompilar y volver atrás sin dramas; el resultado es
54  predecible.
55- **Texto plano + binarios atómicos** → la IA lee/escribe archivos e inspecciona binarios con
56  `readelf`/`objdump`; no parsea bases de datos opacas.
57- **musl legible** → el código C de la libc base es comprensible en el contexto de un LLM
58  (glibc es un laberinto de macros).
59- **Enlazado estático** → una herramienta mutada corre sin romper enlaces de otros programas.
60- **Mutabilidad + overlay** → agencia real con red de seguridad; sin rollbacks pesados.
61
62En distros inmutables/declarativas, la IA tendría que lidiar con generadores de config y
63políticas read-only; en tradicionales, no tendría provenance. `hammer` mantiene las **tuberías
64expuestas y de baja entropía**, que es justo lo que un agente necesita.
65
66## 4. Garantías de seguridad (no negociables)
67
681. **La IA trabaja en overlay por defecto.** Sin capacidad `inject-real`, no puede tocar el
69   FHS base. El flujo es siempre overlay → `commit` humano.
702. **Capacidades mínimas y explícitas.** El humano concede `query`/`compile`/`inject` por
71   separado vía la política del bus ([SDD 07](07-agent-bus.md)).
723. **Toda acción es reversible y registrada.** `discard` revierte el overlay; el `commit`
73   entra al diario firmado ([SDD 05](05-journal.md)).
744. **Recetas, no binarios.** La IA produce `.swm` (fuente + flags + config), no binarios
75   opacos. Lo que comparte es verificable por terceros ([SDD 06](06-swm-format.md)).
765. **El humano tiene la última palabra.** Ningún cambio se vuelve permanente sin `commit`.
77
78## 5. De la intención al `.swm`: el rol del modelo
79
80El traductor intención→`.swm` es un LLM. Detalles de modelo/API (Claude, herramientas, prompts)
81se documentarán aparte cuando se implemente la Fase 6; aquí sólo fijamos el contrato:
82
83- **Entrada:** intención en NL + contexto del sistema (qué herramientas hay, qué pins, estado
84  de servicios — todo consultable por `QUERY`).
85- **Salida:** un `.swm` válido ([SDD 06](06-swm-format.md)) + un plan de verificación.
86- **El modelo no ejecuta nada directamente:** emite comandos por el bus, que `hammerd` valida
87  contra las capacidades concedidas.
88
89## 6. Lenguaje de consulta/transformación (visión, Fase posterior)
90
91Para que la IA refiera partes del sistema sin rutas absolutas frágiles, un mini-lenguaje de
92consulta sobre el grafo del sistema:
93
94```
95find /service/web -where "depends_on(libssl)" -> replace_with my_tls
96```
97
98El daemon traduce esa consulta estructurada a acciones reales del bus. La terminal sigue siendo
99el lugar de validación final. Esto es visión, no Fase 0 — se diseñará cuando el bucle básico
100esté probado.
101
102## 7. Interfaz
103
104```rust
105// cliente del bus (puede vivir en un crate aparte hammer-agent en Fase 6)
106pub trait AgentClient {
107    fn hello(&mut self) -> Result<Caps>;
108    fn compile(&mut self, recipe: &Recipe) -> Result<ArtifactHash>;
109    fn inject(&mut self, h: &ArtifactHash, target: &Path, overlay: OverlayId) -> Result<()>;
110    fn query(&mut self, q: Query) -> Result<QueryResult>;
111    fn events(&mut self) -> impl Iterator<Item = BusEvent>;
112}
113```