hammer/docs/08-ai-integration.md

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) y de un overlay (SDD 04). 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).
3. Toda acción es reversible y registrada. discard revierte el overlay; el commit entra al diario firmado (SDD 05).
4. Recetas, no binarios. La IA produce .swm (fuente + flags + config), no binarios opacos. Lo que comparte es verificable por terceros (SDD 06).
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) + 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

// 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>;
}