system-docs/02_COMPONENTES/internos/oracle.md

# Oracle (Prospectiva)

**Estado:** Especificación completa - Implementación pendiente
**Puerto propuesto:** 5055

## Descripción

Módulo de análisis prospectivo del Sistema de Registro Inmutable. Permite explorar escenarios futuros mediante la manipulación de supuestos inciertos, manteniendo inmutables los datos históricos y el modelo de cálculo.

```
┌─────────────────────────────────────────────────────────────────┐
│                    PRINCIPIO ORACLE                              │
│                                                                 │
│   "No predecimos el futuro. Documentamos qué pasaría            │
│    SI ciertos supuestos se cumplen.                             │
│    La honestidad está en los supuestos, no en el resultado."    │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

## Ficha Técnica

| Atributo | Valor |
|----------|-------|
| Nombre | Oracle |
| Descriptor | prospectiva |
| Versión personal | Oracle (DECK) |
| Versión corporativa | Oracle (CORP) |
| Puerto | 5055 |
| Mutabilidad | Inmutable post-emisión |
| Persistencia | Permanente |
| Eliminación | Prohibida |

## Posición en el Sistema

Oracle implementa la **Capa 2: Análisis Prospectivo** del marco de Contabilidad Bifurcada:

```
┌─────────────────────────────────────────────────────────────────┐
│  CAPA 1: REGISTRO HISTÓRICO (implementada)                      │
│  Clara/Margaret → Mason → Feldman → [NOTARIO]                   │
│  Hechos consumados, inmutables, verificables                    │
└─────────────────────────────────────────────────────────────────┘
                              │
                              │ alimenta (solo lectura)
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│  CAPA 2: ANÁLISIS PROSPECTIVO (Oracle)                          │
│  Supuestos explícitos + Escenarios + Sensibilidad               │
│  Proyecciones documentadas, auditables, no vinculantes          │
└─────────────────────────────────────────────────────────────────┘
```

## Flujo de Datos

```
Feldman (libros contables)
       │
       │ consulta (solo lectura)
       ▼
Oracle (prospectiva)
       │
       ├── Genera análisis con hash (mrf)
       ├── Usuario explora escenarios
       ├── Guarda escenarios (inmutables)
       │
       ▼
[Almacenamiento propio de Oracle]
       │
       │ [cuando el horizonte temporal se cumple]
       ▼
Contraste con realidad (datos nuevos de Feldman)
       │
       └── Métricas de calibración
```

## Relación con Componentes

| Componente | Relación | Descripción |
|------------|----------|-------------|
| **Feldman** | Entrada (solo lectura) | Única fuente de datos. Oracle nunca escribe en Feldman |
| **Grace** | Colaboración | Ejecuta modelos vía S-CONTRACT, sugiere supuestos |
| **Sentinel** | Verificación | Valida integridad de análisis y escenarios |
| **ITM** | Informativo | Oracle puede evaluar viabilidad de items/objetivos |
| **MST** | Informativo | Oracle puede evaluar probabilidad de cumplimiento |
| **BCK** | Calibración | Bloques consolidados permiten contrastar predicción vs realidad |

## Arquitectura del Análisis

Cada análisis Oracle es una unidad atómica con 7 secciones:

### 1. Datos Base

| Campo | Tipo | Descripción |
|-------|------|-------------|
| h_bloques_feldman | Array[mrf] | Referencias a bloques de Feldman |
| periodo_inicio | Date | Inicio del período histórico |
| periodo_fin | Date | Fin del período histórico |
| h_dataset | mrf | Hash de integridad del conjunto |

### 2. Supuestos

Lista exhaustiva de afirmaciones no verificables:

| Campo | Tipo | Descripción |
|-------|------|-------------|
| id | String | Identificador (ej: SUP_001) |
| name_es | String | Nombre en español |
| txt | Text | Descripción |
| tipo | Enum | porcentaje, moneda, cantidad, booleano |
| valor_defecto | Numeric | Valor por defecto |
| rango_min | Numeric | Mínimo plausible |
| rango_max | Numeric | Máximo plausible |
| fuente_tipo | Enum | histórico, estimación_externa, juicio_experto |
| confianza | Enum | alta, media, baja |

### 3. Modelo

| Campo | Tipo | Descripción |
|-------|------|-------------|
| name_es | String | Nombre del modelo |
| version | String | Versión del modelo |
| metodologia | Text | Descripción de la metodología |
| formulas | JSONB | Fórmulas de cálculo |
| limitaciones | Text | Condiciones de no aplicabilidad |

### 4. Escenarios (Obligatorios)

| Escenario | Descripción |
|-----------|-------------|
| **Base** | Supuestos en valores por defecto |
| **Optimista** | Supuestos ajustados favorablemente |
| **Pesimista** | Supuestos ajustados desfavorablemente |
| **Estrés** | Límites del modelo - qué tendría que pasar para resultado inaceptable |

### 5. Sensibilidad

| Campo | Tipo | Descripción |
|-------|------|-------------|
| contribucion | JSONB | % de cada supuesto en varianza total |
| supuestos_criticos | Array | Top 3 supuestos más influyentes |

### 6. Resultado

Nunca cifra única:

| Campo | Tipo | Descripción |
|-------|------|-------------|
| rango_min | Numeric | Límite inferior |
| rango_max | Numeric | Límite superior |
| punto_medio | Numeric | Valor central |
| horizonte | String | Período de proyección |
| unidad | String | Unidad de medida |

### 7. Metadata

| Campo | Tipo | Descripción |
|-------|------|-------------|
| mrf | VARCHAR(64) | Hash público del análisis |
| private_mrf | VARCHAR(64) | Hash privado (prueba de propiedad) |
| date | Date | Fecha de emisión |
| fecha_caducidad | Date | Cuándo expira el análisis |
| condiciones_invalidacion | Text | Qué haría el análisis inaplicable |

## Interfaz de Escenarios

```
┌─────────────────────────────────────────────────────────────────┐
│                    PRINCIPIO DE SEPARACIÓN                       │
│                                                                 │
│   INMUTABLE (no se toca)         VARIABLE (el usuario mueve)   │
│   ----------------------         --------------------------     │
│   - Datos históricos             - Supuestos macro             │
│   - Fórmulas del modelo          - Tasas estimadas             │
│   - Reglas de cálculo            - Probabilidades asignadas    │
│   - Metodología aplicada         - Horizontes temporales       │
│                                                                 │
│   "Cambias lo incierto, no lo calculado"                        │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

Cada supuesto se presenta como slider con:
- Nombre descriptivo
- Valor actual (posición del slider)
- Rango Min-Max
- Fuente del valor por defecto
- Indicador de confianza (alta/media/baja)

Cada movimiento dispara recálculo en tiempo real.

## Reglas de Validación (O-*)

| Código | Nombre | Descripción | Severidad |
|--------|--------|-------------|-----------|
| O-001 | Trazabilidad total | Todo dato debe tener mrf de Feldman | CRITICAL |
| O-002 | Supuesto explícito | Ningún supuesto implícito permitido | CRITICAL |
| O-003 | Sin cifra única | Resultados siempre como rango | HIGH |
| O-004 | Modelo nombrado | No metodologías ad-hoc | HIGH |
| O-005 | Caducidad obligatoria | fecha_caducidad requerido | HIGH |
| O-006 | Condición invalidación | condiciones_invalidacion requerido | HIGH |
| O-007 | Conservación permanente | Eliminación prohibida | CRITICAL |
| O-008 | Escenarios obligatorios | Los 4 escenarios requeridos | HIGH |
| O-009 | Sensibilidad visible | Campo sensibilidad requerido | MEDIUM |
| O-010 | Inmutabilidad post-emisión | Solo INSERT, nunca UPDATE | CRITICAL |

## Integración con Grace (S-CONTRACT)

| Módulo Grace | Uso en Oracle |
|--------------|---------------|
| PREDICTOR | Generar pronósticos base |
| CLUSTERER | Agrupar escenarios similares |
| SCORER | Evaluar calidad de supuestos |
| NARRATOR | Generar informe en lenguaje natural |
| AUDITOR | Detectar anomalías en proyecciones |

## Ciclo de Retroalimentación

Cuando el horizonte temporal se cumple:

1. Oracle recupera datos reales de Feldman
2. Compara supuestos usados vs valores reales
3. Compara resultado proyectado vs resultado observado
4. Calcula % error por supuesto incorrecto vs limitación modelo

## Métricas de Calibración

| Métrica | Descripción |
|---------|-------------|
| Sesgo de supuestos | "Tus estimaciones de crecimiento son 15% optimistas" |
| Precisión de rangos | "90% de veces el resultado cayó en tu rango" |
| Sensibilidad real vs estimada | "Dijiste inflación, pero fue tipo de cambio" |

## Lo que Oracle NO es

- No es sistema de alertas
- No toma decisiones
- No modifica datos de Feldman
- No genera "la respuesta correcta"
- No sustituye juicio humano

## Limitaciones Conocidas

| Limitación | Descripción |
|------------|-------------|
| No captura cisnes negros | Eventos radicalmente improbables no aparecen |
| Depende de calidad Feldman | Datos incorrectos = análisis heredan problemas |
| Modelos son simplificaciones | No capturan toda la realidad |
| Pasado no garantiza futuro | Cambios de régimen difíciles de anticipar |

---

*SKYNET v10.1 - Oracle - 6 Enero 2026*