system-docs/v4-archive/contratos-comunes/README.md

# Contratos Comunes - Sistema GRACE

**Version:** 2.1
**Estado:** Enterprise Standard

Especificacion del contrato comun (S-CONTRACT) y contratos de modulo (M-CONTRACT) para el ecosistema de microservicios cognitivos GRACE.

---

## Arquitectura

```
Alfred (Orquestador n8n)
           |
           | S-CONTRACT v2.0
           v
+-------------------+
|       GRACE       |
|  18 Microservicios|
|     Cognitivos    |
+-------------------+
           |
           v
    SYS_LOG + SFE
```

**Filosofia:** "Alfred Decide, GRACE Transforma"

---

## Estructura del Repositorio

```
contratos-comunes/
+-- README.md                    # Este archivo
+-- docs/
|   +-- S-CONTRACT.md            # Contrato comun del sistema (v2.1)
|   +-- MODULOS_IA.md            # Catalogo de 18 modulos
|   +-- ARQUITECTURA.md          # Vision arquitectonica
|   +-- SENTINEL.md              # Sistema de auditoria
|   +-- KEY_VAULT.md             # Gestion de llaves y cifrado
|   +-- NOTARIO.md               # Sellado blockchain
|   +-- IMPLEMENTACION.md        # Wrappers y ejemplos
+-- schemas/
|   +-- s-contract-request.json  # JSON Schema para requests (v2.1)
|   +-- s-contract-response.json # JSON Schema para responses (v2.1)
+-- m-contracts/
|   +-- CLASSIFIER.json          # M-CONTRACT clasificador
|   +-- OCR_CORE.json            # M-CONTRACT OCR
|   +-- ASR_ENGINE.json          # M-CONTRACT ASR
|   +-- ...                      # (18 modulos total)
+-- db-schemas/                  # NUEVO: Schemas PostgreSQL
|   +-- 00_types.sql             # Tipos enumerados
|   +-- 01_hst_tags.sql          # Sistema de etiquetas HST
|   +-- 02_task_manager.sql      # Gestor de tareas
|   +-- 03_work_log.sql          # Log de trabajo
|   +-- 04_ai_context.sql        # Contexto para IA
|   +-- 05_ai_requests.sql       # Log de requests IA
+-- archive/                     # Versiones obsoletas
```

---

## Documentos Principales

| Documento | Descripcion | Prioridad |
|-----------|-------------|-----------|
| [S-CONTRACT.md](docs/S-CONTRACT.md) | Especificacion del contrato comun v2.0 | LEER PRIMERO |
| [MODULOS_IA.md](docs/MODULOS_IA.md) | Catalogo de los 18 modulos GRACE | Alta |
| [ARQUITECTURA.md](docs/ARQUITECTURA.md) | Vision arquitectonica del sistema | Alta |
| [HST_API.md](docs/HST_API.md) | API de etiquetas HST v2.0 (tzrtech.org) | Alta |
| [SENTINEL.md](docs/SENTINEL.md) | Sistema de auditoria dual (LIGHT/DEEP) | Media |
| [KEY_VAULT.md](docs/KEY_VAULT.md) | Gestion de llaves y cifrado | Media |
| [NOTARIO.md](docs/NOTARIO.md) | Sellado blockchain | Media |
| [IMPLEMENTACION.md](docs/IMPLEMENTACION.md) | Wrappers Python/JS y ejemplos n8n | Referencia |
| [db-schemas/README.md](db-schemas/README.md) | Schemas PostgreSQL compartidos | Alta |

---

## Database Schemas (db-schemas/)

Schemas PostgreSQL compartidos por todos los componentes del ecosistema:

| Schema | Descripción |
|--------|-------------|
| `hst_tags` | Sistema de etiquetas unificado (HST/EMP/HSU/PJT) |
| `task_manager` | Proyectos, milestones, bloques y tareas |
| `task_work_log` | Log de archivos entrantes/salientes |
| `task_contexts` | Contexto enviado a servicios IA |
| `task_ai_requests` | Log de todas las requests a IA |

Ver [db-schemas/README.md](db-schemas/README.md) para documentación completa.

---

## Conceptos Clave

### S-CONTRACT (Contrato del Sistema)
Marco general que define:
- Estructura de requests/responses
- Trazabilidad (trace_id, step_id, idempotency_key)
- Perfiles FULL/LITE
- Logging (SYS_LOG)
- Seguridad y cifrado

### M-CONTRACT (Contrato de Modulo)
Cada modulo extiende S-CONTRACT con:
- Schemas de input/output especificos
- Cadena de fallback
- Metricas de calidad baseline
- Providers disponibles

### Perfiles

| Perfil | Uso | Campos |
|--------|-----|--------|
| FULL | Flujos criticos, auditoria completa | Todos |
| LITE | Operaciones rapidas, alto volumen | Minimos |

### Status Codes

- `SUCCESS` - Ejecucion completa
- `PARTIAL` - Resultado incompleto pero usable
- `ERROR` - Fallo no recuperable
- `TIMEOUT` - Excedio TTL
- `FALLBACK` - Exito con modulo alternativo

---

## Los 18 Modulos GRACE

| Familia | Modulos |
|---------|---------|
| VISION | IMG_PREPROCESS, PDF_SCANNER, OCR_CORE |
| VOZ | ASR_ENGINE, TTS_ENGINE |
| IDENTIDAD | FACE_VECTOR, ID_CONSOLIDATION, AVATAR_GEN |
| SEMANTICA | EMBEDDINGS, SUMMARIZER, TASK_EXTRACTOR, CLASSIFIER, SIMILARITY |
| UTILIDADES | FIELD_EXTRACTOR, HASHER, INPUT_NORMALIZER, OUTPUT_ADAPTER, LANG_DETECT |

---

## Ejemplo Rapido

### Request LITE
```json
{
  "contract_version": "2.0",
  "profile": "LITE",
  "envelope": {
    "trace_id": "550e8400-e29b-41d4-a716-446655440000",
    "idempotency_key": "a1b2c3d4e5f6..."
  },
  "routing": {"module": "CLASSIFIER"},
  "context": {"lang": "es", "mode": "strict"},
  "payload": {
    "type": "text",
    "encoding": "utf-8",
    "content": "Factura de Telefonica por 45.99 EUR"
  }
}
```

### Response
```json
{
  "contract_version": "2.0",
  "profile": "LITE",
  "envelope": {"trace_id": "550e8400-...", "idempotency_key": "a1b2c3d4..."},
  "status": {"code": "SUCCESS", "provider_used": "groq"},
  "result": {
    "schema": "classifier_output_v1",
    "data": {"category": "FINANZAS", "confidence": 0.98}
  },
  "quality": {"confidence": 0.98, "coverage": 1.0},
  "errors": []
}
```

---

## Historial de Versiones

| Version | Fecha | Cambios |
|---------|-------|---------|
| 1.0 | 2025-12-01 | Version inicial |
| 1.1 | 2025-12-01 | Jerarquia S/M-CONTRACT |
| 1.2 | 2025-12-01 | Consolidacion, modularizacion |
| 2.0 | 2025-12-18 | Nomenclatura GRACE, reorganizacion repo |
| 2.1 | 2025-12-18 | Modos de despliegue (EXTERNAL/SELF_HOSTED/SEMI), db-schemas |

---

## Repositorios Relacionados

- `deck` - Servidor central, iniciador de conexiones
- `grace` - Capa de procesamiento IA
- `penny` - Asistente de voz real-time
- `the-factory` - Procesamiento documental
- `mason` - Constructor de prompts
- `hst` - Sistema de etiquetas HST

---

*Sistema GRACE - "Alfred Decide, GRACE Transforma"*
# Hook test Wed Dec 24 00:21:51 UTC 2025