docs: enterprise refactor plan with ralph specs

.ralph/specs/legacy/interfaces.md

@@ -0,0 +1,164 @@
+# 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
+}
+```