# CONTRATO COMUN DEL SISTEMA (S-CONTRACT)
**Version:** 2.1
**Estado:** Enterprise Standard - Implementacion Ready
**Filosofia Base:** Interoperabilidad Total - Trazabilidad Absoluta - Resiliencia Hibrida - Privacidad por Diseno

---

# Historial de Versiones

| Version | Fecha | Cambios Principales |
|---------|-------|---------------------|
| 1.0 | 2025-12-01 | Version inicial: contrato unico, SENTINEL, SYS_LOG |
| 1.1 | 2025-12-01 | Jerarquia S/M-CONTRACT, perfiles FULL/LITE, batch, seguridad |
| 1.2 | 2025-12-01 | Consolidacion completa, modularizacion documental |
| 2.0 | 2025-12-18 | Nomenclatura actualizada (JARVIS -> GRACE), reorganizacion repo |
| 2.1 | 2025-12-18 | Modos de despliegue, context extendido (system_instruction, datasets, tags, ambiente) |

## Cambios clave v2.0 -> v2.1

1. **Seccion 5: Modos de Despliegue y Conectividad** - Nueva seccion que define:
   - DECK como unico iniciador de conexiones
   - Tres modos: `EXTERNAL`, `SELF_HOSTED`, `SEMI`
   - Bloque `deployment` en requests
   - Gestion de credenciales desde DECK
   - Comportamiento especifico por servicio (GRACE, PENNY, THE FACTORY)

2. **Nuevo bloque `deployment`** en request para especificar modo de operacion.

3. **Nuevo campo `deployment_used`** en response para indicar que modo/proveedor se uso.

4. **Bloque `context` extendido** con campos para IA:
   - `system_instruction`: Prompt/instruccion del sistema
   - `datasets[]`: Array de datasets (knowledge, examples, rules, vocabulary, context, persona)
   - `tags{}`: Etiquetas HST por grupo (hst, hsu, emp, pjt)
   - `ambiente{}`: Variables de contexto ambiental (timezone, locale, currency, session_type)

5. **Glosario ampliado** con terminos de despliegue y servicios.

## Cambios clave v1.2 -> v2.0

1. **Nomenclatura actualizada** - Sistema cognitivo renombrado de JARVIS a GRACE.

2. **Reorganizacion documental** - Estructura simplificada:
   - `S-CONTRACT.md` (este documento) - Marco general
   - `SENTINEL.md` - Sistema de auditoria
   - `IMPLEMENTACION.md` - Wrappers y ejemplos
   - `KEY_VAULT.md` - Gestion de llaves
   - `NOTARIO.md` - Sellado blockchain
   - `MODULOS_IA.md` - Catalogo de 18 modulos
   - `ARQUITECTURA.md` - Vision arquitectonica

3. **Archivado de versiones anteriores** - Documentos legacy movidos a `archive/`.

---

# 1. Proposito del Contrato Comun

El Contrato Comun es la **interfaz universal jerarquica** que garantiza:

```
+---------------------------------------------------------------------+
|                    PRINCIPIO FUNDAMENTAL                             |
|                                                                      |
|   "Un modulo que no cumple el contrato, no existe para Alfred"       |
+---------------------------------------------------------------------+
```

- **Interoperabilidad**: Todos los modulos hablan un lenguaje compatible.
- **Trazabilidad**: Logging consistente en todo el ecosistema.
- **Intercambiabilidad**: Anadir o sustituir modulos sin romper el sistema.
- **Privacidad**: No datos flotantes, cifrado por diseno.

---

# 2. Jerarquia de Contratos

## 2.1 Arquitectura de Tres Niveles

```
+---------------------------------------------------------------------+
|                     S-CONTRACT (Sistema)                             |
|         Marco general: trazas, routing, contexto, seguridad          |
+---------------------------------------------------------------------+
                              |
          +-------------------+-------------------+
          |                   |                   |
          v                   v                   v
+-----------------+ +-----------------+ +-----------------+
|   M-CONTRACT    | |   M-CONTRACT    | |   M-CONTRACT    |
|   CLASSIFIER    | |    OCR_CORE     | |   ASR_ENGINE    |
|                 | |                 | |                 |
| - schema_input  | | - schema_input  | | - schema_input  |
| - schema_output | | - schema_output | | - schema_output |
| - perfiles      | | - perfiles      | | - perfiles      |
| - latencias     | | - latencias     | | - latencias     |
+-----------------+ +-----------------+ +-----------------+
                              |
                              v
                    +-----------------+
                    |    PERFILES     |
                    |  FULL  |  LITE  |
                    +-----------------+
```

## 2.2 S-CONTRACT (Contrato General del Sistema)

Define los conceptos y campos minimos obligatorios:
- Trazas (`envelope`)
- Enrutamiento (`routing`)
- Contexto (`context`)
- Carga util (`payload`)
- Almacenamiento (`storage`)
- Procesamiento por lotes (`batch`)
- Seguridad (`security`)
- Calidad (`quality`)
- Auditoria (`audit`)

## 2.3 M-CONTRACT (Contrato de Modulo)

Cada modulo declara su **propio contrato** que extiende el S-CONTRACT:

```json
{
  "module": "CLASSIFIER",
  "version": "1.0",
  "extends": "S-CONTRACT-2.0",
  "profiles_supported": ["FULL", "LITE"],
  "capabilities": {
    "payload_types": ["text"],
    "max_input_tokens": 8000,
    "expected_latency_ms": 500,
    "batch_support": true,
    "batch_max_items": 100
  },
  "schemas": {
    "input": "classifier_input_v1",
    "output": "classifier_output_v1"
  },
  "fallback_chain": ["CLASSIFIER_LOCAL", "CLASSIFIER_GROQ", "CLASSIFIER_OPENAI"],
  "quality_baseline": {
    "min_confidence": 0.7,
    "expected_confidence": 0.9
  }
}
```

---

# 3. Perfiles de Contrato: FULL vs LITE

## 3.1 Comparativa de Perfiles

| Aspecto | FULL | LITE |
|---------|------|------|
| **Uso tipico** | Flujos criticos, auditoria | Operaciones rapidas |
| **Trazabilidad** | Completa (todos los campos) | Basica (trace_id + idempotency) |
| **Pasos intermedios** | Persistidos | Opcionales |
| **Auditoria SENTINEL** | LIGHT + DEEP | Solo LIGHT |
| **Consolidacion blockchain** | Si | No |
| **Overhead** | ~2KB por request | ~200B por request |

## 3.2 Perfil FULL

Orientado a:
- Flujos largos y complejos
- Procesos criticos de negocio
- Auditoria SENTINEL-LIGHT/DEEP completa
- Consolidacion en blockchain

**Campos obligatorios**: Todos los bloques del S-CONTRACT.

## 3.3 Perfil LITE

Orientado a:
- Clasificaciones simples
- Embeddings de texto
- Utilidades rapidas
- Alto volumen / baja latencia

**Campos obligatorios minimos**:

| Campo | Obligatorio | Motivo |
|-------|-------------|--------|
| `contract_version` | Si | Compatibilidad |
| `profile` | Si | Identificacion |
| `envelope.trace_id` | Si | Trazabilidad minima |
| `envelope.idempotency_key` | Si | Evitar reprocesamiento |
| `routing.module` | Si | Destino |
| `payload` | Si | Datos a procesar |
| `context.lang` | Opcional | Idioma |
| `context.mode` | Opcional | Modo de operacion |

---

# 4. Especificacion del Contrato (v2.0)

## 4.1 REQUEST - Perfil FULL

```json
{
  "contract_version": "2.0",
  "profile": "FULL",

  "envelope": {
    "trace_id": "uuid-v4-global",
    "parent_trace_id": "uuid-v4-padre|null",
    "step_id": "uuid-v4-paso-actual",
    "step_index": 1,
    "total_steps": 5,
    "idempotency_key": "sha256-del-input",
    "timestamp_init": "2025-12-18T10:30:00.000Z",
    "ttl_ms": 30000,
    "provider_timeout_ms": 15000
  },

  "routing": {
    "module": "CLASSIFIER",
    "version": "1.0",
    "provider_preference": ["local", "groq", "openrouter"],
    "fallback_chain": ["CLASSIFIER_LOCAL", "CLASSIFIER_GROQ", "CLASSIFIER_OPENAI"],
    "max_fallback_level": 2
  },

  "context": {
    "lang": "es",
    "mode": "strict",
    "pii_filter": true,
    "bandera_id": "uuid-jurisdiccion",
    "player_id": "uuid-actor",
    "method_hash": "sha256-metodo-activo",
    "human_readable": "Clasificacion de email cliente-001",

    "system_instruction": "Clasifica el contenido segun taxonomia HST...",
    "datasets": [
      {"codigo": "DS_TAXONOMY", "tipo": "vocabulary", "contenido": "..."}
    ],
    "tags": {
      "hst": ["h_maestro_1", "h_maestro_2"],
      "hsu": [],
      "emp": [],
      "pjt": []
    },
    "ambiente": {
      "timezone": "Europe/Madrid",
      "locale": "es-ES",
      "currency": "EUR",
      "session_type": "batch"
    }
  },

  "payload": {
    "type": "text|image|audio|document|structured",
    "encoding": "utf-8|base64|url",
    "content": "...",
    "content_hash": "sha256-del-contenido",
    "schema_expected": "nombre-del-schema-salida"
  },

  "batch": {
    "is_batch": false,
    "batch_id": null,
    "item_index": null,
    "items_total": 1,
    "batch_mode": "SEQUENTIAL|PARALLEL"
  },

  "storage": {
    "input_location": "internal|external|local_ephemeral|client_side",
    "input_ref": "hostinger://path|s3://bucket/key",
    "output_location": "internal|external",
    "output_ref": "hostinger://path|s3://bucket/key",
    "persist_intermediate": true,
    "retention_days": 30
  },

  "security": {
    "encryption_profile": "NONE|E2E_BASIC|E2E_STRICT",
    "data_sensitivity": "LOW|MEDIUM|HIGH|SECRET",
    "key_vault_ref": "kv://profile/uuid",
    "pii_detected": false,
    "gdpr_relevant": false
  }
}
```

### Campos del Envelope

| Campo | Tipo | Obligatorio | Descripcion |
|-------|------|-------------|-------------|
| `trace_id` | UUID v4 | Si | ID unico de la ejecucion completa |
| `parent_trace_id` | UUID v4 / null | No | Referencia al proceso padre |
| `step_id` | UUID v4 | Si | ID unico de este paso especifico |
| `step_index` | integer | Si | Posicion en la cadena (1-indexed) |
| `total_steps` | integer | No | Total estimado de pasos |
| `idempotency_key` | SHA256 | Si | Hash del contenido para deduplicacion |
| `timestamp_init` | ISO8601 | Si | Momento de creacion |
| `ttl_ms` | integer | No | Tiempo maximo de vida (default: 30000) |
| `provider_timeout_ms` | integer | No | Timeout especifico del proveedor |

### Campos de Routing

| Campo | Tipo | Obligatorio | Descripcion |
|-------|------|-------------|-------------|
| `module` | string | Si | Nombre del modulo destino |
| `version` | semver | No | Version del M-CONTRACT |
| `provider_preference` | array | No | Orden de preferencia |
| `fallback_chain` | array | No | Modulos alternativos |
| `max_fallback_level` | integer | No | Maximo nivel de degradacion |

### Tipos de Storage Location

| Tipo | Descripcion | TTL Default | Verificacion |
|------|-------------|-------------|--------------|
| `internal` | Hostinger/Nextcloud | 90 dias | Hash al guardar |
| `external` | S3/GCS/Azure | 1 ano | Hash + versioning |
| `local_ephemeral` | Temporal destruible | 24 horas | Hash en memoria |
| `client_side` | Dispositivo usuario | N/A | Hash obligatorio en request |

---

## 4.2 REQUEST - Perfil LITE

```json
{
  "contract_version": "2.0",
  "profile": "LITE",

  "envelope": {
    "trace_id": "uuid-v4-global",
    "idempotency_key": "sha256-del-input"
  },

  "routing": {
    "module": "CLASSIFIER"
  },

  "context": {
    "lang": "es",
    "mode": "strict"
  },

  "payload": {
    "type": "text",
    "encoding": "utf-8",
    "content": "Texto a clasificar"
  }
}
```

**Regla de oro**: Un modulo que soporta LITE **no puede exigir** campos adicionales.

---

## 4.3 RESPONSE - Universal (FULL/LITE)

```json
{
  "contract_version": "2.0",
  "profile": "FULL|LITE",

  "envelope": {
    "trace_id": "uuid-v4-global",
    "step_id": "uuid-v4-paso-actual",
    "step_index": 1,
    "idempotency_key": "sha256-del-input",
    "timestamp_init": "2025-12-18T10:30:00.000Z",
    "timestamp_end": "2025-12-18T10:30:00.450Z"
  },

  "status": {
    "code": "SUCCESS|PARTIAL|ERROR|TIMEOUT|FALLBACK",
    "fallback_level_used": 0,
    "provider_used": "local|groq|openrouter",
    "module_instance": "CLASSIFIER_GROQ_V1"
  },

  "result": {
    "schema": "classifier_output_v1",
    "data": {
      "category": "FINANZAS",
      "confidence": 0.98,
      "subcategory": "FACTURA",
      "tags": ["proveedor", "mensual"]
    }
  },

  "quality": {
    "confidence": 0.98,
    "coverage": 1.0,
    "tokens_input": 150,
    "tokens_output": 45,
    "validation_passed": true,
    "schema_valid": true
  },

  "metadata": {
    "model_id": "llama-3-70b-instruct",
    "model_version": "2024-03",
    "processing_ms": 450,
    "queue_wait_ms": 12,
    "retries": 0,
    "cost_units": 0.0012
  },

  "storage": {
    "output_persisted": true,
    "output_ref": "hostinger://processed/2025/12/18/uuid.json",
    "output_hash": "sha256-del-output",
    "intermediate_refs": []
  },

  "audit": {
    "sentinel_light_checked": false,
    "sentinel_deep_checked": false,
    "sentinel_findings_ref": null,
    "blockchain_pending": false,
    "blockchain_tx_ref": null,
    "notario_batch_id": null
  },

  "errors": [],
  "warnings": []
}
```

### Codigos de Status

| Codigo | Significado | Accion Alfred | Logging |
|--------|-------------|---------------|---------|
| `SUCCESS` | Ejecucion completa y valida | Continuar flujo | INFO |
| `PARTIAL` | Resultado incompleto pero usable | Evaluar `coverage` | WARN |
| `ERROR` | Fallo no recuperable | Activar fallback o abortar | ERROR |
| `TIMEOUT` | Excedio TTL o provider_timeout | Activar fallback | WARN |
| `FALLBACK` | Exito usando modulo alternativo | Continuar + log | INFO |

---

# 5. Modos de Despliegue y Conectividad

## 5.1 Principio Fundamental: DECK como Iniciador

```
+---------------------------------------------------------------------+
|                    PRINCIPIO DE CONECTIVIDAD                         |
|                                                                      |
|   "DECK inicia TODAS las conexiones. Los servicios son stateless.   |
|    Cada request lleva su contexto completo. Nada se asume."         |
+---------------------------------------------------------------------+
```

DECK (el servidor personal del usuario) es el **unico punto que inicia conexiones**:

- DECK → PENNY (sesiones de voz)
- DECK → GRACE (procesamiento cognitivo via Alfred)
- DECK → THE FACTORY (generacion de contenido)

Los servicios **nunca** inician conexiones hacia DECK. Son receptores pasivos que:
- Reciben contexto completo en cada request
- Procesan sin estado persistente
- Devuelven resultado y olvidan

## 5.2 Modos de Despliegue

Cada servicio puede operar en tres modos:

| Modo | Codigo | Descripcion |
|------|--------|-------------|
| **Externo** | `EXTERNAL` | Solo APIs comerciales (OpenAI, Anthropic, etc.) |
| **Autoalojado** | `SELF_HOSTED` | Solo infraestructura propia (RunPod, servidor local) |
| **Semi-automatico** | `SEMI` | Hibrido con fallback automatico |

### 5.2.1 Modo EXTERNAL

```
DECK ──────────────────────────────► APIs Comerciales
                                     (OpenAI, Anthropic, Groq, etc.)
```

- Sin infraestructura propia
- Pago por uso a proveedores
- Maxima disponibilidad, minimo mantenimiento
- Datos salen del control del usuario

### 5.2.2 Modo SELF_HOSTED

```
DECK ──────────────────────────────► Infraestructura Propia
                                     (RunPod, Modal, servidor local)
```

- Control total de datos
- Coste fijo o por uso de GPU
- Requiere mantenimiento
- Zero datos a terceros

### 5.2.3 Modo SEMI (Semi-automatico)

```
DECK ─────┬────────────────────────► Infraestructura Propia (prioridad)
          │                               │
          │                               │ (si falla/timeout)
          │                               ▼
          └────────────────────────► APIs Comerciales (fallback)
```

- Intenta primero autoalojado
- Fallback a externo si falla
- Balance entre control y disponibilidad
- Configuracion de preferencias por servicio

## 5.3 Configuracion de Deployment en Request

El bloque `deployment` es **opcional** y define el modo de operacion:

```json
{
  "contract_version": "2.0",
  "profile": "FULL",

  "deployment": {
    "mode": "SEMI",
    "tier_preference": ["SELF_HOSTED", "EXTERNAL"],
    "self_hosted": {
      "endpoint": "https://runpod.example.com/v2/abc123/runsync",
      "timeout_ms": 30000,
      "retry_on_failure": true
    },
    "external": {
      "providers_allowed": ["groq", "openai", "anthropic"],
      "providers_blocked": [],
      "max_cost_per_request": 0.10
    },
    "credentials_ref": "kv://deck/credentials/grace"
  },

  "envelope": {...},
  "routing": {...},
  "payload": {...}
}
```

### Campos de Deployment

| Campo | Tipo | Obligatorio | Descripcion |
|-------|------|-------------|-------------|
| `mode` | enum | Si | `EXTERNAL`, `SELF_HOSTED`, `SEMI` |
| `tier_preference` | array | No | Orden de preferencia de tiers |
| `self_hosted.endpoint` | URL | Condicional | Endpoint del servicio autoalojado |
| `self_hosted.timeout_ms` | integer | No | Timeout para autoalojado |
| `self_hosted.retry_on_failure` | boolean | No | Reintentar antes de fallback |
| `external.providers_allowed` | array | No | Lista blanca de proveedores |
| `external.providers_blocked` | array | No | Lista negra de proveedores |
| `external.max_cost_per_request` | decimal | No | Limite de coste por request |
| `credentials_ref` | string | No | Referencia a credenciales en Key Vault |

## 5.4 Credenciales desde DECK

DECK **siempre** proporciona las credenciales necesarias. Los servicios **nunca** almacenan credenciales.

### Opcion A: Referencia a Key Vault

```json
{
  "deployment": {
    "mode": "SEMI",
    "credentials_ref": "kv://deck/credentials/grace"
  }
}
```

El servicio resuelve la referencia contra el Key Vault de DECK.

### Opcion B: Credenciales en Request (conexiones seguras)

```json
{
  "deployment": {
    "mode": "EXTERNAL",
    "credentials": {
      "openai": {"api_key": "sk-..."},
      "anthropic": {"api_key": "sk-ant-..."},
      "groq": {"api_key": "gsk_..."}
    }
  }
}
```

Solo permitido con `encryption_profile: E2E_STRICT` y conexiones mTLS.

## 5.5 Comportamiento por Servicio

### GRACE (Capa Cognitiva)

| Modo | Tier 1 | Tier 2 |
|------|--------|--------|
| `EXTERNAL` | - | APIs comerciales |
| `SELF_HOSTED` | RunPod Serverless, Local | - |
| `SEMI` | RunPod Serverless → | APIs comerciales (fallback) |

```json
{
  "routing": {
    "module": "ASR_ENGINE",
    "fallback_chain": ["ASR_FASTER_WHISPER", "ASR_GROQ", "ASR_OPENAI"]
  },
  "deployment": {
    "mode": "SEMI",
    "tier_preference": ["SELF_HOSTED", "EXTERNAL"],
    "self_hosted": {
      "endpoint": "https://api.runpod.ai/v2/asr-whisper/runsync"
    }
  }
}
```

### PENNY (Asistente de Voz)

| Modo | ASR | LLM | TTS |
|------|-----|-----|-----|
| `EXTERNAL` | Groq/OpenAI | Claude/GPT | ElevenLabs |
| `SELF_HOSTED` | Faster Whisper | Qwen/Llama | XTTS-v2 |
| `SEMI` | Faster Whisper → Groq | Qwen → Claude | XTTS → ElevenLabs |

```json
{
  "type": "session_start",
  "deployment": {
    "mode": "SEMI",
    "components": {
      "asr": {"preference": ["SELF_HOSTED", "EXTERNAL"]},
      "llm": {"preference": ["SELF_HOSTED", "EXTERNAL"]},
      "tts": {"preference": ["SELF_HOSTED", "EXTERNAL"]}
    },
    "self_hosted": {
      "endpoint": "wss://runpod-penny.example.com/ws/voice"
    },
    "external": {
      "llm_provider": "anthropic",
      "tts_provider": "elevenlabs"
    }
  },
  "planos": {...}
}
```

### THE FACTORY (Generacion de Contenido)

| Modo | Generacion | Post-procesado |
|------|------------|----------------|
| `EXTERNAL` | APIs comerciales (Midjourney, DALL-E) | APIs |
| `SELF_HOSTED` | RunPod (SDXL, Flux) | Local |
| `SEMI` | RunPod → | APIs comerciales (fallback) |

## 5.6 Response con Informacion de Deployment

El response incluye que modo/proveedor se uso:

```json
{
  "status": {
    "code": "SUCCESS",
    "deployment_used": {
      "mode": "SEMI",
      "tier_used": "SELF_HOSTED",
      "provider_used": "runpod",
      "endpoint_used": "https://api.runpod.ai/v2/asr-whisper/runsync",
      "fallback_activated": false
    }
  },
  "result": {...}
}
```

Si hubo fallback:

```json
{
  "status": {
    "code": "FALLBACK",
    "deployment_used": {
      "mode": "SEMI",
      "tier_used": "EXTERNAL",
      "provider_used": "groq",
      "fallback_activated": true,
      "fallback_reason": "SELF_HOSTED_TIMEOUT",
      "original_tier": "SELF_HOSTED",
      "original_error": "Timeout after 30000ms"
    }
  }
}
```

## 5.7 Configuracion Default en DECK

DECK mantiene configuracion por defecto para cada servicio:

```yaml
# deck/config/deployment.yaml

defaults:
  mode: SEMI
  tier_preference: [SELF_HOSTED, EXTERNAL]

services:
  grace:
    mode: SEMI
    self_hosted:
      endpoint: https://api.runpod.ai/v2/${RUNPOD_GRACE_ID}/runsync
      timeout_ms: 30000
    external:
      providers_allowed: [groq, openai, anthropic]

  penny:
    mode: SEMI
    self_hosted:
      endpoint: wss://${RUNPOD_PENNY_HOST}/ws/voice
      timeout_ms: 5000
    external:
      llm_provider: anthropic
      tts_provider: elevenlabs

  factory:
    mode: SEMI
    self_hosted:
      endpoint: https://api.runpod.ai/v2/${RUNPOD_FACTORY_ID}/runsync
      timeout_ms: 120000
    external:
      providers_allowed: [replicate, stability]

credentials:
  ref: kv://deck/credentials
  # O inline (solo desarrollo):
  # groq_key: gsk_...
  # openai_key: sk-...
```

---

# 6. Batch Processing

## 6.1 Filosofia

```
+---------------------------------------------------------------------+
|                    PRINCIPIO DE BATCH                                |
|                                                                      |
|  "Todos los datos entran solidos y se procesan solidos.             |
|   Nunca datos flotantes. Cada item tiene su trace_id."              |
+---------------------------------------------------------------------+
```

## 6.2 Campos de Batch

```json
"batch": {
  "is_batch": true,
  "batch_id": "uuid-batch",
  "item_index": 15,
  "items_total": 120,
  "batch_mode": "PARALLEL",
  "batch_priority": "NORMAL|HIGH|LOW",
  "batch_deadline": "2025-12-18T18:00:00.000Z"
}
```

---

# 7. Sistema de Logging (SYS_LOG)

## 7.1 Filosofia

```
+---------------------------------------------------------------------+
|                    PRINCIPIO DE LOGGING                              |
|                                                                      |
|   "Si no esta en el log, no ocurrio. Si ocurrio, esta en log."      |
+---------------------------------------------------------------------+
```

## 7.2 Arquitectura de Libros

```
+---------------------------------------------------------------------+
|                      SYS_LOG (Libro Diario)                          |
|              Registro de TODOS los eventos del sistema               |
+---------------------------------------------------------------------+
                              |
                              | (procesos exitosos)
                              v
+---------------------------------------------------------------------+
|                      SFE (Libro Mayor)                               |
|              Solo procesos completados y validados                   |
+---------------------------------------------------------------------+
                              |
                              | (consolidacion periodica)
                              v
+---------------------------------------------------------------------+
|                      NOTARIO (Blockchain)                            |
|              Sellado inmutable de registros criticos                 |
+---------------------------------------------------------------------+
```

## 7.3 Estructura de Tabla SYS_LOG

```sql
CREATE TABLE SYS_LOG (
  -- IDENTIFICACION
  id                    UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  trace_id              UUID NOT NULL,
  parent_trace_id       UUID,
  step_id               UUID NOT NULL UNIQUE,
  idempotency_key       CHAR(64) NOT NULL,

  -- SECUENCIA Y TIPO
  step_index            INTEGER NOT NULL,
  step_type             VARCHAR(20) NOT NULL,
  profile               VARCHAR(10) DEFAULT 'FULL',

  -- BATCH
  batch_id              UUID,
  batch_item_index      INTEGER,
  batch_items_total     INTEGER,

  -- TEMPORALIDAD
  timestamp_created     TIMESTAMPTZ DEFAULT NOW(),
  timestamp_started     TIMESTAMPTZ,
  timestamp_completed   TIMESTAMPTZ,
  duration_ms           INTEGER,
  queue_wait_ms         INTEGER,

  -- MODULO Y PROVEEDOR
  module_name           VARCHAR(50) NOT NULL,
  module_version        VARCHAR(20),
  provider_requested    VARCHAR(50),
  provider_used         VARCHAR(50),
  fallback_level        INTEGER DEFAULT 0,
  model_id              VARCHAR(100),
  model_version         VARCHAR(50),

  -- ESTADO Y ERRORES
  status_code           VARCHAR(20) NOT NULL,
  error_code            VARCHAR(50),
  error_message         TEXT,
  retries               INTEGER DEFAULT 0,

  -- PAYLOAD (Referencias, NO datos crudos)
  input_hash            CHAR(64) NOT NULL,
  input_ref             TEXT NOT NULL,
  input_size_bytes      BIGINT,
  input_type            VARCHAR(20),
  output_hash           CHAR(64),
  output_ref            TEXT,
  output_size_bytes     BIGINT,
  intermediate_refs     JSONB DEFAULT '[]',

  -- CALIDAD
  confidence            DECIMAL(5,4),
  coverage              DECIMAL(5,4),
  tokens_input          INTEGER,
  tokens_output         INTEGER,
  validation_passed     BOOLEAN,
  schema_valid          BOOLEAN,

  -- COSTOS
  cost_units            DECIMAL(12,8),
  cost_currency         VARCHAR(3) DEFAULT 'USD',

  -- CONTEXTO
  bandera_id            UUID,
  player_id             UUID,
  method_hash           CHAR(64),
  human_readable        TEXT,

  -- SEGURIDAD
  encryption_profile    VARCHAR(20) DEFAULT 'NONE',
  data_sensitivity      VARCHAR(20) DEFAULT 'LOW',
  key_vault_ref         TEXT,
  pii_detected          BOOLEAN DEFAULT FALSE,

  -- AUDITORIA
  audit_status          VARCHAR(20) DEFAULT 'PENDING',
  audit_light_ts        TIMESTAMPTZ,
  audit_deep_ts         TIMESTAMPTZ,
  audit_result          JSONB,

  -- BLOCKCHAIN
  blockchain_pending    BOOLEAN DEFAULT FALSE,
  blockchain_tx_ref     VARCHAR(100),
  notario_batch_id      UUID,

  -- CONSTRAINTS
  CONSTRAINT valid_status CHECK (
    status_code IN ('PENDING', 'RUNNING', 'SUCCESS', 'PARTIAL', 'ERROR', 'TIMEOUT', 'FALLBACK', 'CANCELLED')
  ),
  CONSTRAINT valid_step_type CHECK (
    step_type IN ('INIT', 'VALIDATE', 'ROUTE', 'TRANSFORM', 'FALLBACK', 'PERSIST', 'NOTIFY', 'COMPLETE', 'ERROR', 'AUDIT', 'CANCEL')
  ),
  CONSTRAINT valid_profile CHECK (
    profile IN ('FULL', 'LITE')
  )
);

-- INDICES
CREATE INDEX idx_syslog_trace ON SYS_LOG(trace_id);
CREATE INDEX idx_syslog_created ON SYS_LOG(timestamp_created);
CREATE INDEX idx_syslog_status ON SYS_LOG(status_code);
CREATE INDEX idx_syslog_module ON SYS_LOG(module_name, timestamp_created);
CREATE INDEX idx_syslog_batch ON SYS_LOG(batch_id) WHERE batch_id IS NOT NULL;
CREATE INDEX idx_syslog_idempotency ON SYS_LOG(idempotency_key);
```

## 7.4 Tipos de Step

| Tipo | Descripcion | Duracion Tipica |
|------|-------------|-----------------|
| `INIT` | Entrada inicial al sistema | <10ms |
| `VALIDATE` | Validacion de entrada y permisos | <50ms |
| `ROUTE` | Decision de modulo y proveedor | <10ms |
| `TRANSFORM` | Procesamiento por modulo IA | 100ms-30s |
| `FALLBACK` | Activacion de modulo alternativo | <10ms |
| `PERSIST` | Escritura a almacenamiento | 50-500ms |
| `NOTIFY` | Notificacion externa | 100-2000ms |
| `COMPLETE` | Finalizacion exitosa | <10ms |
| `ERROR` | Registro de fallo | <10ms |
| `AUDIT` | Registro de auditoria SENTINEL | Variable |

---

# 8. Almacenamiento Dual

## 8.1 Estructura

### Interno (Hostinger/Nextcloud)

```
/data/
+-- original/              # Archivos crudos de entrada
|   +-- YYYY/MM/DD/
+-- processed/             # Resultados finales
|   +-- YYYY/MM/DD/
+-- intermediate/          # Pasos intermedios
|   +-- {trace_id}/
+-- cache/                 # Cache de resultados
+-- ephemeral/             # Temporal destruible (24h)
```

### Externo (S3/GCS)

```
bucket-grace-{env}/
+-- archive/               # Largo plazo (1+ anos)
+-- backup/                # Respaldos criticos
+-- heavy/                 # Archivos grandes
+-- exports/               # Exportaciones para usuarios
```

## 8.2 URIs de Referencia

```
# Interno
hostinger://original/2025/12/18/abc123_factura.pdf
hostinger://processed/2025/12/18/abc123_output.json

# Externo
s3://grace-prod/archive/2025/12/abc123.tar.gz

# Key Vault
kv://production/encryption/abc123
```

---

# 9. Seguridad y Cifrado

## 9.1 Perfiles de Cifrado

| Perfil | Transporte | Reposo | Uso Tipico |
|--------|------------|--------|------------|
| `NONE` | TLS 1.3 | Sin cifrar | Datos publicos |
| `E2E_BASIC` | TLS 1.3 | AES-256 | Datos internos |
| `E2E_STRICT` | mTLS | AES-256-GCM | PII, financiero |

## 9.2 Niveles de Sensibilidad

| Nivel | Ejemplos | Cifrado Minimo | Retencion Max |
|-------|----------|----------------|---------------|
| `LOW` | Logs tecnicos | NONE | 1 ano |
| `MEDIUM` | Emails, documentos | E2E_BASIC | 90 dias |
| `HIGH` | Facturas, contratos | E2E_BASIC | 30 dias |
| `SECRET` | PII, biometria | E2E_STRICT | 7 dias |

Ver `KEY_VAULT.md` para especificacion completa.

---

# 10. Auditoria (SENTINEL)

## 10.1 Arquitectura Dual

| Componente | SENTINEL-LIGHT | SENTINEL-DEEP |
|------------|----------------|---------------|
| **Motor** | Reglas + ML local | LLM pesado (remoto) |
| **Frecuencia** | Cada 5 minutos | Cada hora + escalados |
| **Cobertura** | 100% registros | Muestreo + errores |
| **Latencia** | <100ms/registro | 2-5s/analisis |

Ver `SENTINEL.md` para especificacion completa.

---

# 11. Notario y Blockchain

## 11.1 Ciclo Basico

```
Alfred procesa -> SYS_LOG (diario)
       |
SENTINEL audita -> AUDIT_RESULTS
       |
NOTARIO agrupa -> Batch de sellado
       |
Blockchain -> tx_ref inmutable
```

Ver `NOTARIO.md` para especificacion completa.

---

# 12. Catalogo de Modulos GRACE

| ID | Nombre | Familia | Descripcion |
|----|--------|---------|-------------|
| 1 | IMG_PREPROCESS | VISION | Normalizacion de imagenes |
| 2 | PDF_SCANNER | VISION | Limpieza de PDFs escaneados |
| 3 | OCR_CORE | VISION | Extraccion de texto |
| 4 | ASR_ENGINE | VOZ | Reconocimiento de habla |
| 5 | TTS_ENGINE | VOZ | Sintesis de voz |
| 6 | FACE_VECTOR | IDENTIDAD | Vector biometrico facial |
| 7 | ID_CONSOLIDATION | IDENTIDAD | Fusion de identidades |
| 8 | AVATAR_GEN | IDENTIDAD | Generacion de avatar |
| 9 | EMBEDDINGS | SEMANTICA | Vectorizacion semantica |
| 10 | SUMMARIZER | SEMANTICA | Resumen estructurado |
| 11 | TASK_EXTRACTOR | SEMANTICA | Extraccion de tareas |
| 12 | CLASSIFIER | SEMANTICA | Clasificacion de contenido |
| 13 | SIMILARITY | SEMANTICA | Comparacion vectorial |
| 14 | FIELD_EXTRACTOR | UTILIDADES | Extraccion de campos |
| 15 | HASHER | UTILIDADES | Generacion de hashes |
| 16 | INPUT_NORMALIZER | UTILIDADES | Normalizacion de entradas |
| 17 | OUTPUT_ADAPTER | UTILIDADES | Adaptacion de salidas |
| 18 | LANG_DETECT | UTILIDADES | Deteccion de idioma |

Ver `MODULOS_IA.md` para especificacion detallada de cada modulo.

---

# 13. Documentos Relacionados

| Documento | Contenido |
|-----------|-----------|
| `SENTINEL.md` | Sistema de auditoria completo |
| `IMPLEMENTACION.md` | Wrappers Python/JS, ejemplos |
| `KEY_VAULT.md` | Gestion de llaves y cifrado |
| `NOTARIO.md` | Sellado y consolidacion blockchain |
| `MODULOS_IA.md` | Catalogo de 18 modulos GRACE |
| `ARQUITECTURA.md` | Vision arquitectonica del sistema |

---

# 14. Checklist de Implementacion

## Para nuevos modulos (M-CONTRACT):

- [ ] Declarar perfiles soportados (FULL, LITE)
- [ ] Declarar schemas de entrada/salida
- [ ] Definir latencias esperadas y baseline de calidad
- [ ] Definir comportamiento en batch
- [ ] Implementar soporte de encryption_profile minimo E2E_BASIC
- [ ] Documentar fallback_chain
- [ ] Probar integracion con SENTINEL

## Para Alfred (orquestador):

- [ ] Soportar construccion de requests FULL/LITE
- [ ] Validar request contra S-CONTRACT antes de enviar
- [ ] Validar response antes de persistir
- [ ] Gestionar colas usando batch_id + SYS_LOG
- [ ] Evitar datos flotantes (siempre *_ref solido)
- [ ] Respetar ttl_ms y provider_timeout_ms
- [ ] Registrar TODOS los pasos en SYS_LOG

---

# 15. Glosario

| Termino | Definicion |
|---------|------------|
| **S-CONTRACT** | Contrato General del Sistema, marco comun obligatorio |
| **M-CONTRACT** | Contrato especifico de un modulo |
| **Perfil FULL** | Uso con trazabilidad y auditoria completa |
| **Perfil LITE** | Uso ligero, minimo necesario |
| **trace_id** | Identificador unico de una ejecucion completa |
| **step_id** | Identificador unico de un paso especifico |
| **idempotency_key** | Hash que permite detectar operaciones duplicadas |
| **fallback_chain** | Lista ordenada de modulos alternativos |
| **Key Vault** | Almacenamiento seguro de llaves y credenciales |
| **Libro Diario** | SYS_LOG, registro de todos los eventos |
| **Libro Mayor** | SFE, solo procesos completados y validados |
| **NOTARIO** | Modulo de consolidacion y sellado blockchain |
| **SENTINEL-LIGHT** | Auditor rapido, exhaustivo, basado en reglas |
| **SENTINEL-DEEP** | Auditor profundo, muestreo + errores, basado en LLM |
| **GRACE** | Sistema cognitivo de 18 microservicios IA |
| **DECK** | Servidor personal del usuario, inicia todas las conexiones |
| **PENNY** | Asistente personal de voz conversacional |
| **THE FACTORY** | Sistema de generacion de contenido |
| **Modo EXTERNAL** | Despliegue usando solo APIs comerciales externas |
| **Modo SELF_HOSTED** | Despliegue usando solo infraestructura propia |
| **Modo SEMI** | Despliegue hibrido con fallback automatico |
| **tier_preference** | Orden de preferencia de tiers (SELF_HOSTED, EXTERNAL) |
| **credentials_ref** | Referencia a credenciales en Key Vault de DECK |

---

**Fin del Documento S-CONTRACT - Version 2.1**

*Sistema GRACE - "Alfred Decide, GRACE Transforma"*