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         │  takana 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: takana commit (promueve + diario) o takana 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. `takana` 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` se conecta detrás del trait `IntentTranslator` del crate
81`takana-agent`. Contrato:
82
83- **Entrada:** intención en NL + `SystemContext` (lo que el orquestador recolecta por
84  `QUERY`: `BaseRef` local, extras JSON).
85- **Salida:** un `Swm` válido ([SDD 06](06-swm-format.md)).
86
87Fase 6 entrega un `MockTranslator` que resuelve intentos contra un `IntentCatalog` YAML
88(intent exacto → `.swm` inline o `swm_path` relativo). Eso permite probar el bucle sin LLM:
89el humano que descubrió la intención con un modelo real congela el resultado y los CI lo
90reproducen byte-a-byte. El traductor LLM (Claude API u otro) implementa el mismo trait y se
91enchufa sin tocar el `Orchestrator`.
92
93**El modelo nunca ejecuta nada directamente:** emite comandos por el bus, que `hammerd`
94valida contra las capacidades concedidas, y el `Orchestrator` traduce las mutaciones a
95`takana-core::apply` o a `Compile` por el bus.
96
97## 6. Lenguaje de consulta/transformación (visión, Fase posterior)
98
99Para que la IA refiera partes del sistema sin rutas absolutas frágiles, un mini-lenguaje de
100consulta sobre el grafo del sistema:
101
102```
103find /service/web -where "depends_on(libssl)" -> replace_with my_tls
104```
105
106El daemon traduce esa consulta estructurada a acciones reales del bus. La terminal sigue siendo
107el lugar de validación final. Esto es visión, no Fase 0 — se diseñará cuando el bucle básico
108esté probado.
109
110## 7. Interfaz
111
112El crate `takana-agent` (Fase 6) expone:
113
114```rust
115// takana_agent::client
116pub struct AgentClient { pub welcome: Welcome, /* … */ }
117impl AgentClient {
118    pub fn connect(sock: &Path) -> Result<Self>;
119    pub fn compile(&mut self, recipe: RecipeInline, timeout: Duration) -> Result<String>; // artifact
120    pub fn inject(&mut self, artifact: &str, target: &str, overlay: Option<&str>, t: Duration) -> Result<usize>;
121    pub fn query_file(&mut self, path: &str, timeout: Duration) -> Result<serde_json::Value>;
122    pub fn init(&mut self, cmd: &str, timeout: Duration) -> Result<()>;
123    pub fn drain_async(&self) -> Vec<Event>;
124    pub fn next_async(&self, timeout: Duration) -> Result<Event>;
125}
126
127// takana_agent::translator
128pub trait IntentTranslator { fn translate(&self, intent: &str, ctx: &SystemContext) -> Result<Swm, TranslateError>; }
129pub struct MockTranslator { /* HashMap<intent, Swm> */ }
130pub struct IntentCatalog { pub intents: Vec<CatalogEntry> }  // YAML loader
131
132// takana_agent::orchestrator
133pub struct Orchestrator<T: IntentTranslator> { /* … */ }
134impl<T> Orchestrator<T> {
135    pub fn new(t: T, base: BaseRef, apply: ApplyTarget, compile: CompileMode) -> Self;
136    pub fn run(&self, intent: &str) -> Result<Proposal>;
137}
138```
139
140Los tipos del protocolo (`Command`/`Event`/`Cap`/`Peer`/`RecipeInline`) viven en
141`takana-core::proto` para ser compartidos por `hammerd`, `takana-agent` y cualquier cliente
142externo escrito en Rust.