Update Context Manager v8.1 - new log schema with TZZR components integration

03_MODELO_DATOS/context_manager_v8.md

@@ -0,0 +1,346 @@
+# Context Manager v8 - Sistema de Gestión de Contexto para IA
+
+**Versión:** 8.1
+**Fecha:** 2026-01-01
+**Sistema:** CAPTAIN CLAUDE - TZZR
+**Generador:** ARCHITECT
+
+---
+
+## Visión General
+
+El **Context Manager v8** es un sistema completo para la gestión del contexto en sistemas de IA. Proporciona:
+
+1. **Log inmutable** con integridad criptográfica (blockchain-style)
+2. **Integración con Sistema de Componentes TZZR** (players, items, locations, hashtags, flags)
+3. **Referencias relacionales** a contexto, libros contables y registros de secretaría
+4. **Contexto ambiental** dinámico embebido en mensajes
+5. **Soporte multiagente** con owner, players y master_player
+
+---
+
+## Arquitectura de Schemas
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    CONTEXT MANAGER v8.1                     │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │  SCHEMA: log (Inmutable)                            │   │
+│  │                                                     │   │
+│  │  ├── log.messages      (mensajes)                   │   │
+│  │  └── log.message_refs  (referencias a contexto)     │   │
+│  │                                                     │   │
+│  │  Características:                                   │   │
+│  │  ├─ Solo INSERT (UPDATE/DELETE bloqueados)          │   │
+│  │  ├─ Cadena SHA-256: prev_hash → hash                │   │
+│  │  └─ Integración con Sistema Componentes TZZR        │   │
+│  └─────────────────────────────────────────────────────┘   │
+│                           │                                 │
+│                           ▼                                 │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │  SISTEMA DE COMPONENTES TZZR (Referencias externas) │   │
+│  │                                                     │   │
+│  │  ├── ply  (Players: usuarios, agentes, empresas)    │   │
+│  │  ├── hst  (Hash Semantic Tagging: etiquetas)        │   │
+│  │  ├── flg  (Flags: jurisdicciones, normativas)       │   │
+│  │  ├── itm  (Items: productos, componentes)           │   │
+│  │  └── loc  (Locations: ubicaciones físicas)          │   │
+│  └─────────────────────────────────────────────────────┘   │
+│                           │                                 │
+│                           ▼                                 │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │  FUENTES DE CONOCIMIENTO (via message_refs)         │   │
+│  │                                                     │   │
+│  │  ├── context    → log.messages (historial)          │   │
+│  │  ├── accountant → libros contables                  │   │
+│  │  └── secretary  → registros de secretaría           │   │
+│  └─────────────────────────────────────────────────────┘   │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Schema LOG (2 tablas)
+
+### 1. `log.messages` - Mensajes
+
+Almacena todos los mensajes del sistema de forma inmutable.
+
+**Características:**
+- Solo permite INSERT (triggers previenen UPDATE/DELETE)
+- Cadena de integridad: cada mensaje contiene hash del anterior
+- Integración completa con Sistema de Componentes TZZR
+- Soporte multiagente: owner (emisor), players (receptores), master_player (líder)
+
+**Schema:**
+```sql
+CREATE TABLE log.messages (
+    id              BIGSERIAL PRIMARY KEY,
+    hash            CHAR(64) UNIQUE NOT NULL,     -- SHA-256 del mensaje
+    session_hash    CHAR(64) NOT NULL,            -- Sesión
+    thread_hash     CHAR(64),                     -- Hilo (nullable)
+    owner_id        CHAR(64) NOT NULL,            -- Emisor (→ ply)
+    players_id      CHAR(64)[] DEFAULT '{}',      -- Receptores (→ ply)
+    master_player   CHAR(64),                     -- Líder/coordinador (→ ply)
+    role            TEXT,                         -- Rol del emisor
+    content         TEXT NOT NULL,                -- Contenido del mensaje
+    attachments     JSONB DEFAULT '{}',           -- Adjuntos
+    prev_hash       CHAR(64),                     -- Hash mensaje anterior
+    hashtags        CHAR(64)[] DEFAULT '{}',      -- Etiquetas (→ hst)
+    flag_id         CHAR(64),                     -- Jurisdicción (→ flg)
+    master_item_id  CHAR(64),                     -- Item principal (→ itm)
+    item_id         CHAR(64)[] DEFAULT '{}',      -- Items relacionados (→ itm)
+    loc_id          CHAR(64),                     -- Ubicación (→ loc)
+    ambient         JSONB,                        -- Contexto ambiental
+    created_at      TIMESTAMPTZ DEFAULT NOW()
+);
+```
+
+**Índices:**
+- `session_hash` - Mensajes de una sesión
+- `thread_hash` - Mensajes de un hilo
+- `owner_id` - Mensajes enviados por
+- `master_player` - Mensajes con líder
+- `prev_hash` - Cadena de integridad
+- `created_at` - Orden cronológico
+- `hashtags` (GIN) - Búsqueda por etiquetas
+- `players_id` (GIN) - Búsqueda por receptores
+- `item_id` (GIN) - Búsqueda por items
+- `flag_id` - Filtrar por jurisdicción
+- `loc_id` - Filtrar por ubicación
+
+---
+
+### 2. `log.message_refs` - Referencias
+
+Relaciona cada mensaje con su contexto y fuentes de conocimiento.
+
+**Características:**
+- Tabla relacional para evitar arrays largos de hashes
+- Tres tipos de referencias: context, accountant, secretary
+- Posición para ordenar el contexto
+- Inmutable como log.messages
+
+**Schema:**
+```sql
+CREATE TABLE log.message_refs (
+    id              BIGSERIAL PRIMARY KEY,
+    message_hash    CHAR(64) NOT NULL,            -- Mensaje que se envía
+    ref_hash        CHAR(64) NOT NULL,            -- Hash de la referencia
+    ref_type        log.ref_type NOT NULL,        -- context|accountant|secretary
+    position        INT NOT NULL,                 -- Orden de la referencia
+    thread_hash     CHAR(64),                     -- Hilo (nullable)
+    UNIQUE(message_hash, ref_hash)
+);
+```
+
+**Tipos de referencia:**
+| Tipo | Descripción |
+|------|-------------|
+| `context` | Mensajes anteriores incluidos como contexto |
+| `accountant` | Registros de libros contables (conocimiento financiero) |
+| `secretary` | Registros de secretaría (conocimiento general) |
+
+---
+
+## Integración con Sistema de Componentes TZZR
+
+El Context Manager referencia las tablas del Sistema de Componentes:
+
+| Campo log.messages | Tabla TZZR | Descripción |
+|-------------------|------------|-------------|
+| `owner_id` | ply | Emisor del mensaje (usuario o agente) |
+| `players_id[]` | ply | Receptores del mensaje |
+| `master_player` | ply | Coordinador en sistemas multiagente |
+| `hashtags[]` | hst | Etiquetas semánticas del mensaje |
+| `flag_id` | flg | Jurisdicción o normativa aplicable |
+| `master_item_id` | itm | Item principal relacionado |
+| `item_id[]` | itm | Items adicionales relacionados |
+| `loc_id` | loc | Ubicación física del contexto |
+
+### Tablas del Sistema de Componentes
+
+```
+PLY (Players)
+├── ply  - Sistema (empresas, entidades oficiales)
+├── plu  - Usuario (contactos personales)
+└── plx  - Compartidos
+
+HST (Hash Semantic Tagging)
+├── hst  - Tags del sistema (658)
+├── spe  - Especificaciones técnicas (145)
+├── vsn  - Visiones/escenas (84)
+├── vue  - Valores humanos (21)
+└── hsu  - Tags de usuario
+
+FLG (Flags/Jurisdicciones)
+├── flg  - Sistema (65 países/normativas)
+└── flu  - Usuario
+
+ITM (Items)
+├── itm  - Sistema
+├── itu  - Usuario
+└── itx  - Compartidos
+
+LOC (Locations)
+├── loc  - Sistema
+├── lou  - Usuario
+└── lox  - Compartidos
+```
+
+---
+
+## Cadena de Integridad
+
+Cada mensaje incluye el hash del anterior, formando una cadena verificable:
+
+```
+msg1.hash = SHA256(msg1_data)
+msg2.prev_hash = msg1.hash
+msg2.hash = SHA256(msg2_data)
+msg3.prev_hash = msg2.hash
+...
+```
+
+**Primer mensaje de sesión:** `prev_hash = NULL`
+
+**Función de hash:**
+```sql
+CREATE FUNCTION log.sha256(data TEXT) RETURNS CHAR(64) AS $$
+BEGIN
+    RETURN encode(digest(data, 'sha256'), 'hex');
+END;
+$$ LANGUAGE plpgsql IMMUTABLE;
+```
+
+---
+
+## Protección de Inmutabilidad
+
+Triggers que previenen modificación:
+
+```sql
+-- Bloquear UPDATE
+CREATE TRIGGER protect_messages_update
+BEFORE UPDATE ON log.messages
+FOR EACH ROW EXECUTE FUNCTION log.prevent_update();
+
+-- Bloquear DELETE
+CREATE TRIGGER protect_messages_delete
+BEFORE DELETE ON log.messages
+FOR EACH ROW EXECUTE FUNCTION log.prevent_delete();
+
+-- Igual para message_refs
+```
+
+---
+
+## Contexto Ambiental (ambient)
+
+Campo JSONB para capturar estado del sistema en el momento del mensaje:
+
+```json
+{
+    "timezone": "Europe/Madrid",
+    "locale": "es-ES",
+    "working_directory": "/home/architect/project",
+    "git_branch": "main",
+    "active_services": ["gitea", "postgresql"],
+    "server": "ARCHITECT",
+    "timestamp_utc": "2026-01-01T12:00:00Z"
+}
+```
+
+Solo se incluye cuando es relevante (nullable en la mayoría de mensajes).
+
+---
+
+## Despliegue
+
+**Servidores activos:**
+
+| Servidor | IP | Base de Datos | Estado |
+|----------|-----|---------------|--------|
+| ARCHITECT | 69.62.126.110 | architect | ✅ Activo |
+| DECK | 72.62.1.113 | tzzr | ✅ Activo |
+| CORP | 92.112.181.188 | tzzr | ✅ Activo |
+
+**Extensiones requeridas:**
+- `pgcrypto` - Para función SHA-256
+- `pgvector` - Para embeddings (opcional, instalado)
+
+**Comando de aplicación:**
+```bash
+sudo -u postgres psql -d [database] -c "$(curl -s http://localhost:3000/admin/context-manager/raw/branch/main/schemas/04_log.sql)"
+```
+
+---
+
+## Flujo de Trabajo
+
+### 1. Insertar mensaje
+
+```sql
+INSERT INTO log.messages (
+    hash, session_hash, owner_id, players_id,
+    content, prev_hash, hashtags, created_at
+) VALUES (
+    log.sha256(...), 'session_abc...', 'owner_hash...',
+    ARRAY['player1_hash...', 'player2_hash...'],
+    'Contenido del mensaje', 'prev_msg_hash...',
+    ARRAY['tag1_hash...'], NOW()
+);
+```
+
+### 2. Añadir referencias de contexto
+
+```sql
+INSERT INTO log.message_refs (
+    message_hash, ref_hash, ref_type, position, thread_hash
+) VALUES
+    ('msg_hash...', 'context_msg_1...', 'context', 1, 'thread...'),
+    ('msg_hash...', 'context_msg_2...', 'context', 2, 'thread...'),
+    ('msg_hash...', 'accountant_record...', 'accountant', 3, 'thread...');
+```
+
+### 3. Consultar mensajes con contexto
+
+```sql
+SELECT
+    m.content,
+    m.owner_id,
+    array_agg(r.ref_hash ORDER BY r.position) as context_refs
+FROM log.messages m
+LEFT JOIN log.message_refs r ON m.hash = r.message_hash
+WHERE m.session_hash = 'session_abc...'
+GROUP BY m.id, m.content, m.owner_id
+ORDER BY m.created_at;
+```
+
+---
+
+## Ubicación de Documentación
+
+| Ubicación | Ruta |
+|-----------|------|
+| Gitea | http://localhost:3000/admin/context-manager |
+| R2 | s3://architect/system/context-manager/ |
+| Skynet v8 | s3://architect/system/skynet v8/03_MODELO_DATOS/ |
+
+---
+
+## Historial de Cambios
+
+| Versión | Fecha | Cambios |
+|---------|-------|---------|
+| 8.0 | 2025-12-30 | Versión inicial con 9 tablas |
+| 8.1 | 2026-01-01 | Simplificación a 2 tablas (log.messages, log.message_refs). Integración con Sistema de Componentes TZZR. Nuevos campos: owner_id, players_id, master_player, flag_id, master_item_id, item_id, loc_id |
+
+---
+
+**Documento generado por:** ARCHITECT
+**Timestamp:** 2026-01-01
+**Versión:** Context Manager v8.1