elsabro 2.3.0 → 3.7.0

package/references/error-contracts-v2.md

@@ -0,0 +1,968 @@
+---
+name: error-contracts-v2
+description: Contratos de error expandidos v2 - Circuit Breaker, Bulkhead, Fallback
+version: 2.0.0
+---
+
+# ELSABRO Error Contracts v2
+
+## Nuevos Contratos (v3.0)
+
+Este documento extiende `/references/error-contracts.md` con 3 nuevos contratos de resiliencia.
+
+```
+┌──────────────────────────────────────────────────────────────────────────┐
+│                    RESILIENCE PATTERNS                                    │
+├──────────────────────────────────────────────────────────────────────────┤
+│                                                                          │
+│   ┌─────────────────┐                                                    │
+│   │     REQUEST     │                                                    │
+│   └────────┬────────┘                                                    │
+│            │                                                             │
+│            ▼                                                             │
+│   ┌─────────────────┐   OPEN?     ┌─────────────────┐                   │
+│   │ CIRCUIT BREAKER │ ──────────► │    FALLBACK     │                   │
+│   └────────┬────────┘             └─────────────────┘                   │
+│            │ CLOSED                                                      │
+│            ▼                                                             │
+│   ┌─────────────────┐   FULL?     ┌─────────────────┐                   │
+│   │    BULKHEAD     │ ──────────► │    FALLBACK     │                   │
+│   └────────┬────────┘             └─────────────────┘                   │
+│            │ OK                                                          │
+│            ▼                                                             │
+│   ┌─────────────────┐                                                    │
+│   │    EXECUTE      │                                                    │
+│   └────────┬────────┘                                                    │
+│            │                                                             │
+│            ▼                                                             │
+│        SUCCESS / FAILURE                                                 │
+│                                                                          │
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Contrato 8: ContractCircuitBreaker
+
+### Propósito
+
+Prevenir cascadas de fallos cortando temporalmente las llamadas a un servicio/agente que está fallando repetidamente.
+
+### Estados del Circuit Breaker
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                     CIRCUIT BREAKER STATES                               │
+├─────────────────────────────────────────────────────────────────────────┤
+│                                                                         │
+│   ┌──────────┐                                                          │
+│   │  CLOSED  │  ◄──────── Estado normal, requests pasan                │
+│   └────┬─────┘                                                          │
+│        │                                                                │
+│        │ failures >= threshold                                          │
+│        ▼                                                                │
+│   ┌──────────┐                                                          │
+│   │   OPEN   │  ◄──────── Circuito abierto, requests bloqueados        │
+│   └────┬─────┘                                                          │
+│        │                                                                │
+│        │ timeout expires                                                │
+│        ▼                                                                │
+│   ┌──────────┐                                                          │
+│   │HALF-OPEN │  ◄──────── Probando si el servicio se recuperó          │
+│   └────┬─────┘                                                          │
+│        │                                                                │
+│   ┌────┴────┐                                                           │
+│   │         │                                                           │
+│ success   failure                                                       │
+│   │         │                                                           │
+│   ▼         ▼                                                           │
+│ CLOSED    OPEN                                                          │
+│                                                                         │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+### Código Ejecutable
+
+```javascript
+/**
+ * ContractCircuitBreaker
+ * Previene cascadas de fallos con pattern circuit breaker
+ */
+class ContractCircuitBreaker {
+  static STATES = {
+    CLOSED: 'CLOSED',
+    OPEN: 'OPEN',
+    HALF_OPEN: 'HALF_OPEN'
+  };
+
+  constructor(options = {}) {
+    this.config = {
+      failureThreshold: options.failureThreshold || 5,
+      successThreshold: options.successThreshold || 2,
+      timeout: options.timeout || 30000,
+      monitorInterval: options.monitorInterval || 5000
+    };
+
+    this.circuits = new Map();
+  }
+
+  /**
+   * Obtiene o crea circuit para un agente
+   */
+  getCircuit(agentId) {
+    if (!this.circuits.has(agentId)) {
+      this.circuits.set(agentId, {
+        state: ContractCircuitBreaker.STATES.CLOSED,
+        failures: 0,
+        successes: 0,
+        lastFailure: null,
+        lastStateChange: Date.now(),
+        stats: {
+          totalCalls: 0,
+          totalFailures: 0,
+          totalSuccesses: 0,
+          tripped: 0
+        }
+      });
+    }
+    return this.circuits.get(agentId);
+  }
+
+  /**
+   * Verifica si se puede ejecutar
+   */
+  canExecute(agentId) {
+    const circuit = this.getCircuit(agentId);
+
+    switch (circuit.state) {
+      case ContractCircuitBreaker.STATES.CLOSED:
+        return { allowed: true, state: 'CLOSED' };
+
+      case ContractCircuitBreaker.STATES.OPEN:
+        // Verificar si timeout expiró
+        if (Date.now() - circuit.lastStateChange >= this.config.timeout) {
+          this.transitionTo(agentId, ContractCircuitBreaker.STATES.HALF_OPEN);
+          return { allowed: true, state: 'HALF_OPEN', warning: 'Testing recovery' };
+        }
+        return {
+          allowed: false,
+          state: 'OPEN',
+          error: {
+            code: 'CIRCUIT_OPEN',
+            severity: 'HIGH',
+            message: `Circuit breaker OPEN for ${agentId}`,
+            retryAfter: this.config.timeout - (Date.now() - circuit.lastStateChange),
+            stats: circuit.stats
+          }
+        };
+
+      case ContractCircuitBreaker.STATES.HALF_OPEN:
+        return { allowed: true, state: 'HALF_OPEN', warning: 'Circuit testing' };
+    }
+  }
+
+  /**
+   * Registra éxito
+   */
+  recordSuccess(agentId) {
+    const circuit = this.getCircuit(agentId);
+    circuit.stats.totalCalls++;
+    circuit.stats.totalSuccesses++;
+
+    if (circuit.state === ContractCircuitBreaker.STATES.HALF_OPEN) {
+      circuit.successes++;
+
+      if (circuit.successes >= this.config.successThreshold) {
+        this.transitionTo(agentId, ContractCircuitBreaker.STATES.CLOSED);
+        return { recovered: true, state: 'CLOSED' };
+      }
+    }
+
+    circuit.failures = 0;
+    return { state: circuit.state };
+  }
+
+  /**
+   * Registra fallo
+   */
+  recordFailure(agentId, error) {
+    const circuit = this.getCircuit(agentId);
+    circuit.stats.totalCalls++;
+    circuit.stats.totalFailures++;
+    circuit.failures++;
+    circuit.lastFailure = { at: Date.now(), error: error?.message };
+
+    if (circuit.state === ContractCircuitBreaker.STATES.HALF_OPEN) {
+      // Fallo durante prueba, volver a OPEN
+      this.transitionTo(agentId, ContractCircuitBreaker.STATES.OPEN);
+      return { tripped: true, state: 'OPEN', reason: 'Failed during recovery test' };
+    }
+
+    if (circuit.state === ContractCircuitBreaker.STATES.CLOSED &&
+        circuit.failures >= this.config.failureThreshold) {
+      this.transitionTo(agentId, ContractCircuitBreaker.STATES.OPEN);
+      circuit.stats.tripped++;
+      return { tripped: true, state: 'OPEN', reason: 'Failure threshold exceeded' };
+    }
+
+    return { state: circuit.state, failures: circuit.failures };
+  }
+
+  /**
+   * Transición de estado
+   */
+  transitionTo(agentId, newState) {
+    const circuit = this.getCircuit(agentId);
+    const oldState = circuit.state;
+
+    circuit.state = newState;
+    circuit.lastStateChange = Date.now();
+    circuit.failures = 0;
+    circuit.successes = 0;
+
+    // Emitir evento para logging
+    this.emitStateChange(agentId, oldState, newState);
+
+    return { from: oldState, to: newState };
+  }
+
+  /**
+   * Reset manual
+   */
+  reset(agentId) {
+    if (this.circuits.has(agentId)) {
+      this.transitionTo(agentId, ContractCircuitBreaker.STATES.CLOSED);
+    }
+  }
+
+  /**
+   * Obtiene estado de todos los circuits
+   */
+  getStatus() {
+    const status = {};
+    for (const [agentId, circuit] of this.circuits) {
+      status[agentId] = {
+        state: circuit.state,
+        failures: circuit.failures,
+        stats: circuit.stats,
+        lastFailure: circuit.lastFailure
+      };
+    }
+    return status;
+  }
+
+  emitStateChange(agentId, from, to) {
+    console.log(`[CircuitBreaker] ${agentId}: ${from} → ${to}`);
+  }
+}
+```
+
+### Notificación al Usuario
+
+```
+╔════════════════════════════════════════════════════════════╗
+║  ⚡ CIRCUIT BREAKER TRIGGERED                              ║
+╠════════════════════════════════════════════════════════════╣
+║                                                            ║
+║  Agent: elsabro-executor                                   ║
+║  State: OPEN                                               ║
+║  Reason: 5 consecutive failures                            ║
+║                                                            ║
+║  Stats:                                                    ║
+║  └─ Total calls: 12                                        ║
+║  └─ Total failures: 7                                      ║
+║  └─ Times tripped: 2                                       ║
+║                                                            ║
+║  Auto-retry in: 30 seconds                                 ║
+║                                                            ║
+╠════════════════════════════════════════════════════════════╣
+║  [w] Wait for auto-retry                                   ║
+║  [r] Reset manually and retry now                          ║
+║  [f] Use fallback agent                                    ║
+║  [a] Abort operation                                       ║
+╚════════════════════════════════════════════════════════════╝
+```
+
+---
+
+## Contrato 9: ContractBulkhead
+
+### Propósito
+
+Aislar fallos limitando la concurrencia por tipo de operación/agente. Evita que un agente problemático consuma todos los recursos.
+
+### Diagrama
+
+```
+┌──────────────────────────────────────────────────────────────────────────┐
+│                        BULKHEAD ISOLATION                                 │
+├──────────────────────────────────────────────────────────────────────────┤
+│                                                                          │
+│   ┌─────────────────────────────────────────────────────────────────┐   │
+│   │                    TOTAL CAPACITY: 10                            │   │
+│   ├─────────────────────────────────────────────────────────────────┤   │
+│   │                                                                  │   │
+│   │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │   │
+│   │  │  EXPLORATION │  │IMPLEMENTATION│  │ VERIFICATION │          │   │
+│   │  │    [3/4]     │  │    [2/4]     │  │    [1/2]     │          │   │
+│   │  ├──────────────┤  ├──────────────┤  ├──────────────┤          │   │
+│   │  │ █ █ █ ░      │  │ █ █ ░ ░      │  │ █ ░          │          │   │
+│   │  └──────────────┘  └──────────────┘  └──────────────┘          │   │
+│   │                                                                  │   │
+│   │  Queued: 2 exploration, 0 implementation, 1 verification         │   │
+│   │                                                                  │   │
+│   └─────────────────────────────────────────────────────────────────┘   │
+│                                                                          │
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+### Código Ejecutable
+
+```javascript
+/**
+ * ContractBulkhead
+ * Aísla fallos con semáforos por tipo de operación
+ */
+class ContractBulkhead {
+  constructor(options = {}) {
+    this.config = {
+      globalLimit: options.globalLimit || 10,
+      queueTimeout: options.queueTimeout || 60000,
+      defaultLimit: options.defaultLimit || 3
+    };
+
+    this.partitions = new Map();
+    this.globalActive = 0;
+    this.queues = new Map();
+  }
+
+  /**
+   * Configura límites por partición
+   */
+  configurePartition(partitionId, limit) {
+    if (!this.partitions.has(partitionId)) {
+      this.partitions.set(partitionId, {
+        limit: limit,
+        active: 0,
+        total: 0,
+        rejected: 0
+      });
+      this.queues.set(partitionId, []);
+    } else {
+      this.partitions.get(partitionId).limit = limit;
+    }
+  }
+
+  /**
+   * Intenta adquirir slot
+   */
+  async acquire(partitionId, options = {}) {
+    const { timeout = this.config.queueTimeout, priority = 0 } = options;
+
+    // Asegurar partición existe
+    if (!this.partitions.has(partitionId)) {
+      this.configurePartition(partitionId, this.config.defaultLimit);
+    }
+
+    const partition = this.partitions.get(partitionId);
+
+    // Verificar límite global
+    if (this.globalActive >= this.config.globalLimit) {
+      return this.enqueueOrReject(partitionId, { timeout, priority, reason: 'global_limit' });
+    }
+
+    // Verificar límite de partición
+    if (partition.active >= partition.limit) {
+      return this.enqueueOrReject(partitionId, { timeout, priority, reason: 'partition_limit' });
+    }
+
+    // Adquirir slot
+    partition.active++;
+    partition.total++;
+    this.globalActive++;
+
+    return {
+      acquired: true,
+      slot: {
+        partitionId,
+        acquiredAt: Date.now(),
+        release: () => this.release(partitionId)
+      },
+      stats: this.getPartitionStats(partitionId)
+    };
+  }
+
+  /**
+   * Encola o rechaza si no hay capacidad
+   */
+  async enqueueOrReject(partitionId, options) {
+    const queue = this.queues.get(partitionId);
+    const partition = this.partitions.get(partitionId);
+
+    // Si la cola está muy llena, rechazar
+    if (queue.length >= partition.limit * 2) {
+      partition.rejected++;
+      return {
+        acquired: false,
+        error: {
+          code: 'BULKHEAD_REJECTED',
+          severity: 'MEDIUM',
+          message: `Partition ${partitionId} at capacity and queue full`,
+          queueLength: queue.length,
+          activeSlots: partition.active,
+          limit: partition.limit
+        }
+      };
+    }
+
+    // Encolar con timeout
+    return new Promise((resolve, reject) => {
+      const timeoutId = setTimeout(() => {
+        // Remover de cola
+        const idx = queue.findIndex(q => q.id === queueEntry.id);
+        if (idx !== -1) queue.splice(idx, 1);
+
+        resolve({
+          acquired: false,
+          error: {
+            code: 'BULKHEAD_TIMEOUT',
+            severity: 'MEDIUM',
+            message: `Timeout waiting for slot in partition ${partitionId}`,
+            waitedMs: options.timeout
+          }
+        });
+      }, options.timeout);
+
+      const queueEntry = {
+        id: `q_${Date.now()}_${Math.random().toString(36).substring(7)}`,
+        priority: options.priority,
+        resolve: (result) => {
+          clearTimeout(timeoutId);
+          resolve(result);
+        },
+        enqueuedAt: Date.now()
+      };
+
+      // Insertar ordenado por prioridad
+      const insertIdx = queue.findIndex(q => q.priority < options.priority);
+      if (insertIdx === -1) {
+        queue.push(queueEntry);
+      } else {
+        queue.splice(insertIdx, 0, queueEntry);
+      }
+    });
+  }
+
+  /**
+   * Libera un slot
+   */
+  release(partitionId) {
+    const partition = this.partitions.get(partitionId);
+    const queue = this.queues.get(partitionId);
+
+    if (partition && partition.active > 0) {
+      partition.active--;
+      this.globalActive--;
+
+      // Procesar cola
+      if (queue && queue.length > 0) {
+        const next = queue.shift();
+        partition.active++;
+        partition.total++;
+        this.globalActive++;
+
+        next.resolve({
+          acquired: true,
+          slot: {
+            partitionId,
+            acquiredAt: Date.now(),
+            waitedMs: Date.now() - next.enqueuedAt,
+            release: () => this.release(partitionId)
+          },
+          stats: this.getPartitionStats(partitionId)
+        });
+      }
+    }
+  }
+
+  /**
+   * Obtiene stats de una partición
+   */
+  getPartitionStats(partitionId) {
+    const partition = this.partitions.get(partitionId);
+    const queue = this.queues.get(partitionId);
+
+    return {
+      partitionId,
+      active: partition?.active || 0,
+      limit: partition?.limit || 0,
+      queued: queue?.length || 0,
+      total: partition?.total || 0,
+      rejected: partition?.rejected || 0,
+      utilization: partition ? (partition.active / partition.limit * 100).toFixed(1) + '%' : '0%'
+    };
+  }
+
+  /**
+   * Obtiene stats globales
+   */
+  getGlobalStats() {
+    const stats = {
+      globalActive: this.globalActive,
+      globalLimit: this.config.globalLimit,
+      partitions: {}
+    };
+
+    for (const [id] of this.partitions) {
+      stats.partitions[id] = this.getPartitionStats(id);
+    }
+
+    return stats;
+  }
+}
+
+// Configuración por defecto para ELSABRO
+const bulkhead = new ContractBulkhead({ globalLimit: 10 });
+bulkhead.configurePartition('exploration', 4);
+bulkhead.configurePartition('implementation', 4);
+bulkhead.configurePartition('verification', 2);
+```
+
+### Notificación al Usuario
+
+```
+╔════════════════════════════════════════════════════════════╗
+║  🔒 BULKHEAD LIMIT REACHED                                 ║
+╠════════════════════════════════════════════════════════════╣
+║                                                            ║
+║  Partition: implementation                                 ║
+║  Status: 4/4 slots in use                                  ║
+║  Queue: 2 waiting                                          ║
+║                                                            ║
+║  Current operations:                                       ║
+║  └─ elsabro-executor: implementing auth (2m 30s)          ║
+║  └─ elsabro-executor: implementing api (1m 45s)           ║
+║  └─ feature-dev:code-architect: designing db (3m 10s)     ║
+║  └─ elsabro-planner: planning tests (45s)                 ║
+║                                                            ║
+╠════════════════════════════════════════════════════════════╣
+║  [w] Wait in queue (estimated: 2-3 min)                    ║
+║  [p] Priority queue (skip ahead)                           ║
+║  [a] Abort and try different approach                      ║
+╚════════════════════════════════════════════════════════════╝
+```
+
+---
+
+## Contrato 10: ContractFallback
+
+### Propósito
+
+Proporcionar comportamiento alternativo cuando un agente/operación falla, permitiendo degradación graceful en lugar de fallo total.
+
+### Estrategias de Fallback
+
+```
+┌──────────────────────────────────────────────────────────────────────────┐
+│                       FALLBACK STRATEGIES                                 │
+├──────────────────────────────────────────────────────────────────────────┤
+│                                                                          │
+│   1. ALTERNATIVE AGENT                                                   │
+│      elsabro-executor fails → use elsabro-quick-dev                     │
+│                                                                          │
+│   2. SIMPLIFIED OPERATION                                                │
+│      Full analysis fails → quick analysis only                          │
+│                                                                          │
+│   3. CACHED RESULT                                                       │
+│      API call fails → return cached response                            │
+│                                                                          │
+│   4. DEFAULT VALUE                                                       │
+│      Config fetch fails → use default config                            │
+│                                                                          │
+│   5. MANUAL OVERRIDE                                                     │
+│      Auto-fix fails → ask user for input                                │
+│                                                                          │
+│   6. GRACEFUL SKIP                                                       │
+│      Optional step fails → skip and continue                            │
+│                                                                          │
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+### Código Ejecutable
+
+```javascript
+/**
+ * ContractFallback
+ * Proporciona comportamiento alternativo cuando operaciones fallan
+ */
+class ContractFallback {
+  constructor() {
+    this.fallbacks = new Map();
+    this.cache = new Map();
+    this.stats = {
+      totalFallbacks: 0,
+      byStrategy: {}
+    };
+  }
+
+  /**
+   * Registra fallback para una operación
+   */
+  register(operationId, fallbackConfig) {
+    this.fallbacks.set(operationId, {
+      strategies: fallbackConfig.strategies || [],
+      maxAttempts: fallbackConfig.maxAttempts || 3,
+      cacheResults: fallbackConfig.cacheResults || false,
+      cacheTTL: fallbackConfig.cacheTTL || 300000
+    });
+  }
+
+  /**
+   * Ejecuta con fallback
+   */
+  async executeWithFallback(operationId, primaryFn, context = {}) {
+    const config = this.fallbacks.get(operationId);
+
+    if (!config) {
+      // Sin fallback registrado, ejecutar directamente
+      return primaryFn();
+    }
+
+    // Intentar operación principal
+    try {
+      const result = await primaryFn();
+
+      // Cache si está habilitado
+      if (config.cacheResults) {
+        this.cacheResult(operationId, result, config.cacheTTL);
+      }
+
+      return { success: true, result, usedFallback: false };
+
+    } catch (primaryError) {
+      // Intentar fallbacks en orden
+      for (const strategy of config.strategies) {
+        try {
+          const fallbackResult = await this.executeFallbackStrategy(
+            strategy,
+            operationId,
+            primaryError,
+            context
+          );
+
+          if (fallbackResult.success) {
+            this.recordFallback(strategy.type);
+            return {
+              success: true,
+              result: fallbackResult.result,
+              usedFallback: true,
+              fallbackType: strategy.type,
+              originalError: primaryError.message
+            };
+          }
+        } catch (fallbackError) {
+          // Continuar al siguiente fallback
+          continue;
+        }
+      }
+
+      // Todos los fallbacks fallaron
+      return {
+        success: false,
+        error: {
+          code: 'ALL_FALLBACKS_FAILED',
+          severity: 'HIGH',
+          message: `Operation ${operationId} and all fallbacks failed`,
+          primaryError: primaryError.message,
+          attemptedFallbacks: config.strategies.map(s => s.type)
+        }
+      };
+    }
+  }
+
+  /**
+   * Ejecuta estrategia de fallback específica
+   */
+  async executeFallbackStrategy(strategy, operationId, error, context) {
+    switch (strategy.type) {
+      case 'alternative_agent':
+        return this.fallbackAlternativeAgent(strategy, context);
+
+      case 'simplified':
+        return this.fallbackSimplified(strategy, context);
+
+      case 'cached':
+        return this.fallbackCached(operationId);
+
+      case 'default':
+        return this.fallbackDefault(strategy);
+
+      case 'manual':
+        return this.fallbackManual(strategy, error, context);
+
+      case 'skip':
+        return this.fallbackSkip(strategy);
+
+      default:
+        throw new Error(`Unknown fallback strategy: ${strategy.type}`);
+    }
+  }
+
+  /**
+   * Fallback: usar agente alternativo
+   */
+  async fallbackAlternativeAgent(strategy, context) {
+    const alternativeAgent = strategy.agent;
+    const simplifiedInputs = strategy.simplifyInputs
+      ? this.simplifyInputs(context.inputs)
+      : context.inputs;
+
+    // Ejecutar agente alternativo
+    const result = await context.agentRegistry.execute(alternativeAgent, {
+      ...simplifiedInputs,
+      isFallback: true
+    });
+
+    return { success: true, result };
+  }
+
+  /**
+   * Fallback: operación simplificada
+   */
+  async fallbackSimplified(strategy, context) {
+    const simplifiedFn = strategy.simplifiedFn;
+
+    if (typeof simplifiedFn === 'function') {
+      const result = await simplifiedFn(context);
+      return { success: true, result };
+    }
+
+    throw new Error('No simplified function provided');
+  }
+
+  /**
+   * Fallback: resultado cacheado
+   */
+  async fallbackCached(operationId) {
+    const cached = this.cache.get(operationId);
+
+    if (cached && Date.now() < cached.expiresAt) {
+      return {
+        success: true,
+        result: cached.result,
+        fromCache: true,
+        cachedAt: cached.cachedAt
+      };
+    }
+
+    throw new Error('No valid cached result');
+  }
+
+  /**
+   * Fallback: valor por defecto
+   */
+  async fallbackDefault(strategy) {
+    return {
+      success: true,
+      result: strategy.defaultValue,
+      isDefault: true
+    };
+  }
+
+  /**
+   * Fallback: intervención manual
+   */
+  async fallbackManual(strategy, error, context) {
+    // Crear interrupt para el usuario
+    return {
+      success: false,
+      requiresManual: true,
+      interrupt: {
+        type: 'FALLBACK_MANUAL',
+        title: strategy.title || 'Manual intervention required',
+        error: error.message,
+        context: context,
+        options: strategy.options || ['retry', 'skip', 'abort']
+      }
+    };
+  }
+
+  /**
+   * Fallback: skip graceful
+   */
+  async fallbackSkip(strategy) {
+    return {
+      success: true,
+      result: null,
+      skipped: true,
+      reason: strategy.reason || 'Optional step skipped due to error'
+    };
+  }
+
+  /**
+   * Cache de resultados
+   */
+  cacheResult(operationId, result, ttl) {
+    this.cache.set(operationId, {
+      result,
+      cachedAt: Date.now(),
+      expiresAt: Date.now() + ttl
+    });
+  }
+
+  /**
+   * Simplifica inputs para fallback
+   */
+  simplifyInputs(inputs) {
+    // Remover campos opcionales/complejos
+    const simplified = { ...inputs };
+    delete simplified.advanced;
+    delete simplified.extra;
+    return simplified;
+  }
+
+  /**
+   * Registra uso de fallback
+   */
+  recordFallback(strategyType) {
+    this.stats.totalFallbacks++;
+    this.stats.byStrategy[strategyType] = (this.stats.byStrategy[strategyType] || 0) + 1;
+  }
+
+  /**
+   * Obtiene estadísticas
+   */
+  getStats() {
+    return this.stats;
+  }
+}
+
+// Configuración por defecto para ELSABRO
+const fallback = new ContractFallback();
+
+// Registro de fallbacks para agentes principales
+fallback.register('elsabro-executor', {
+  strategies: [
+    { type: 'alternative_agent', agent: 'elsabro-quick-dev', simplifyInputs: true },
+    { type: 'cached' },
+    { type: 'manual', title: 'Executor failed, manual intervention needed' }
+  ],
+  cacheResults: true,
+  cacheTTL: 600000
+});
+
+fallback.register('exploration', {
+  strategies: [
+    { type: 'simplified', simplifiedFn: async (ctx) => ({ basic: true, files: [] }) },
+    { type: 'default', defaultValue: { files: [], analysis: 'Unable to explore' } }
+  ]
+});
+
+fallback.register('verification', {
+  strategies: [
+    { type: 'alternative_agent', agent: 'elsabro-verifier' },
+    { type: 'skip', reason: 'Verification skipped, proceed with caution' }
+  ]
+});
+```
+
+### Notificación al Usuario
+
+```
+╔════════════════════════════════════════════════════════════╗
+║  🔄 FALLBACK ACTIVATED                                     ║
+╠════════════════════════════════════════════════════════════╣
+║                                                            ║
+║  Primary operation: elsabro-executor                       ║
+║  Error: Timeout after 5 minutes                            ║
+║                                                            ║
+║  Fallback used: alternative_agent                          ║
+║  Alternative: elsabro-quick-dev                            ║
+║                                                            ║
+║  Note: Using simplified approach. Some features may be     ║
+║  implemented with less optimization.                       ║
+║                                                            ║
+╠════════════════════════════════════════════════════════════╣
+║  Status: Continuing with fallback...                       ║
+╚════════════════════════════════════════════════════════════╝
+```
+
+---
+
+## Integración de los 3 Contratos
+
+### Orden de Evaluación
+
+```javascript
+async function executeWithResilience(operationId, agent, inputs, context) {
+  const circuitBreaker = context.circuitBreaker;
+  const bulkhead = context.bulkhead;
+  const fallbackManager = context.fallbackManager;
+
+  // 1. Verificar Circuit Breaker
+  const circuitCheck = circuitBreaker.canExecute(agent);
+  if (!circuitCheck.allowed) {
+    // Usar fallback si circuit está abierto
+    return fallbackManager.executeWithFallback(
+      operationId,
+      async () => { throw new Error('Circuit open'); },
+      { agent, inputs, reason: 'circuit_open' }
+    );
+  }
+
+  // 2. Adquirir slot de Bulkhead
+  const partition = getPartitionForAgent(agent);
+  const slot = await bulkhead.acquire(partition, { timeout: 60000 });
+
+  if (!slot.acquired) {
+    // Usar fallback si no hay capacidad
+    return fallbackManager.executeWithFallback(
+      operationId,
+      async () => { throw new Error('No capacity'); },
+      { agent, inputs, reason: 'bulkhead_full' }
+    );
+  }
+
+  try {
+    // 3. Ejecutar con fallback support
+    const result = await fallbackManager.executeWithFallback(
+      operationId,
+      async () => executeAgent(agent, inputs),
+      { agent, inputs, agentRegistry: context.agentRegistry }
+    );
+
+    // Registrar éxito en circuit breaker
+    if (result.success && !result.usedFallback) {
+      circuitBreaker.recordSuccess(agent);
+    }
+
+    return result;
+
+  } catch (error) {
+    // Registrar fallo en circuit breaker
+    circuitBreaker.recordFailure(agent, error);
+    throw error;
+
+  } finally {
+    // Siempre liberar slot de bulkhead
+    slot.slot.release();
+  }
+}
+```
+
+---
+
+## Resumen de Contratos v2
+
+| # | Contrato | Propósito | Trigger |
+|---|----------|-----------|---------|
+| 1 | RegistryValidator | Validar existencia de agentes | Antes de Task() |
+| 2 | TaskLifecycle | Estados explícitos de tareas | Transiciones |
+| 3 | TimeoutHandler | Timeouts con escalación | Tiempo excedido |
+| 4 | RetryPolicy | Retry con backoff | Errores transitorios |
+| 5 | ErrorAggregator | Agregación por políticas | Ejecución paralela |
+| 6 | SeverityClassifier | Clasificar errores | Cada error |
+| 7 | SessionValidator | Validar integridad | Inicio/fin sesión |
+| 8 | **CircuitBreaker** | Prevenir cascadas | Fallos repetidos |
+| 9 | **Bulkhead** | Aislar recursos | Límite de concurrencia |
+| 10 | **Fallback** | Degradación graceful | Cualquier fallo |