# ABE — Core Interfaces Specification

## Regla fundamental
`src/core/` solo puede importar desde este documento.
`src/plugins/` implementa estas interfaces, nunca al revés.

---

## IState

Representa un estado único de la aplicación explorada.
```typescript
interface IState {
  id: string;              // hash SHA1 del snapshot DOM + URL
  url: string;             // URL completa en este estado
  title: string;           // document.title
  timestamp: number;       // Date.now() cuando se capturó
  domSnapshot: string;     // outerHTML del body serializado
  visitCount: number;      // cuántas veces se ha visitado este estado
}
```

---

## IAction

Representa una acción que el agente puede ejecutar.
```typescript
interface IAction {
  id: string;              // uuid v4 generado al crear la acción
  type: 'click' | 'fill' | 'navigate' | 'select' | 'submit';
  selector?: string;       // CSS selector del elemento (si aplica)
  value?: string;          // valor a introducir (para fill/select)
  url?: string;            // destino (solo para navigate)
  timestamp: number;       // cuando se ejecutó
  seed: number;            // semilla usada para selección aleatoria
  stateId: string;         // ID del estado desde el que se ejecutó
}
```

---

## IObservation

Lo que el agente observa DESPUÉS de ejecutar una acción.
```typescript
interface IObservation {
  id: string;              // uuid v4
  actionId: string;        // acción que provocó esta observación
  newStateId: string;      // ID del nuevo estado resultante
  httpResponses: IHttpResponse[];  // todas las requests durante la acción
  consoleErrors: string[]; // mensajes de console.error capturados
  jsExceptions: string[];  // excepciones JS no capturadas
  timestamp: number;
}

interface IHttpResponse {
  url: string;
  status: number;
  method: string;
  durationMs: number;
}
```

---

## IAnomaly

Una desviación detectada del comportamiento esperado.
```typescript
interface IAnomaly {
  id: string;              // uuid v4
  type: AnomalyType;
  severity: 'low' | 'medium' | 'high' | 'critical';
  observationId: string;   // observación que la provocó
  actionTrace: IAction[];  // secuencia exacta de acciones que llevaron aquí
  description: string;     // texto legible explicando qué pasó
  evidence: IAnomalyEvidence;
  timestamp: number;
}

type AnomalyType =
  | 'http_error'        // respuesta HTTP 4xx o 5xx
  | 'js_exception'      // excepción JavaScript no capturada
  | 'console_error'     // console.error detectado
  | 'navigation_fail'   // navegación no completada
  | 'element_missing'   // elemento esperado desaparece
  | 'timeout';          // acción excede tiempo límite

interface IAnomalyEvidence {
  screenshotPath?: string;    // ruta relativa al screenshot
  domSnapshotPath?: string;   // ruta relativa al DOM serializado
  httpLog?: IHttpResponse[];  // requests relevantes
  rawErrors?: string[];       // errores textuales originales
}
```

---

## IInteractionAgent (plugin interface)

Lo que cualquier agente de interacción debe implementar.
```typescript
interface IInteractionAgent {
  launch(url: string): Promise<void>;
  close(): Promise<void>;
  discoverActions(state: IState): Promise<IAction[]>;
  executeAction(action: IAction): Promise<IObservation>;
  captureState(): Promise<IState>;
}
```

---

## ICollector (plugin interface)

Lo que cualquier colector de contexto debe implementar.
```typescript
interface ICollector {
  name: string;
  collect(anomaly: IAnomaly, agent: IInteractionAgent): Promise<IAnomalyEvidence>;
}
```

---

## IReproducer

Genera un script de replay a partir de una traza de acciones.
```typescript
interface IReproducer {
  serialize(trace: IAction[]): string;       // JSON serializado
  deserialize(raw: string): IAction[];       // reconstruye la traza
  generateScript(trace: IAction[]): string;  // script Playwright ejecutable
}
```

---

## IExporter (plugin interface)

Transforma una anomalía en un reporte consumible.
```typescript
interface IExporter {
  format: 'markdown' | 'json';
  export(anomaly: IAnomaly, outputDir: string): Promise<string>; // retorna la ruta del archivo generado
}
```

---

## StateGraph

No es una interfaz pero su contrato debe ser explícito.
```typescript
class StateGraph {
  addState(state: IState): void;
  hasState(stateId: string): boolean;
  recordTransition(fromId: string, action: IAction, toId: string): void;
  getUnvisited(): IState[];          // estados con visitCount === 0
  getNextToExplore(): IState | null; // heurística BFS por defecto
  toJSON(): object;                  // serializable para logs
}
```