diff --git a/docs/LOG.md b/docs/LOG.md index 21318cb..0a277ae 100644 --- a/docs/LOG.md +++ b/docs/LOG.md @@ -2,7 +2,7 @@ Log inmutable de mensajes del sistema TZZR. -## Tabla: log.messages +## Tabla 1: log.messages Registra todos los mensajes entre usuarios y agentes IA. @@ -11,35 +11,52 @@ Registra todos los mensajes entre usuarios y agentes IA. | id | BIGSERIAL | Índice incremental | | hash | CHAR(64) | SHA256 único del mensaje | | session_hash | CHAR(64) | SHA256 de la sesión | -| sender_type | ENUM | Tipo de emisor: user, agent, orchestrator, system, tool | -| sender_id | CHAR(64) | Hash del emisor (referencia a players) | -| receiver_type | ENUM | Tipo de receptor: user, agent, orchestrator, system, tool | -| receiver_id | CHAR(64) | Hash del receptor (referencia a players) | -| leader_id | CHAR(64) | Hash del coordinador en multiagente (nullable) | -| role | TEXT | Rol del emisor en el contexto | +| thread_hash | CHAR(64) | SHA256 del hilo (nullable) | +| sender_type | ENUM | user, agent, orchestrator, system, tool | +| sender_id | CHAR(64) | Hash del emisor (ref players) | +| receiver_type | ENUM | user, agent, orchestrator, system, tool | +| receiver_id | CHAR(64) | Hash del receptor (ref players) | +| leader_id | CHAR(64) | Coordinador multiagente (nullable) | +| role | TEXT | Rol del emisor | | content | TEXT | Contenido del mensaje | -| attachments | JSONB | Adjuntos (archivos, datos) | -| prev_hash | CHAR(64) | Hash del mensaje anterior (cadena de integridad) | -| context_hashes | CHAR(64)[] | Hashes de mensajes incluidos como contexto | -| hashtags | CHAR(64)[] | Hashes de etiquetas asociadas | -| ambient | JSONB | Contexto ambiental (nullable, solo cuando aplica) | -| created_at | TIMESTAMPTZ | Timestamp de creación | +| attachments | JSONB | Adjuntos | +| prev_hash | CHAR(64) | Hash mensaje anterior (cadena integridad) | +| hashtags | CHAR(64)[] | Etiquetas asociadas | +| ambient | JSONB | Contexto ambiental (nullable) | +| created_at | TIMESTAMPTZ | Timestamp | + +## Tabla 2: log.message_refs + +Relaciona cada mensaje con su contexto y conocimiento. + +| Campo | Tipo | Descripción | +|-------|------|-------------| +| id | BIGSERIAL | Índice incremental | +| message_hash | CHAR(64) | Mensaje que se envía | +| ref_hash | CHAR(64) | Referencia (mensaje, registro contable, secretaría) | +| ref_type | ENUM | context, accountant, secretary | +| position | INT | Orden de la referencia | +| thread_hash | CHAR(64) | Hilo (nullable) | + +### Tipos de referencia + +- **context**: Mensajes anteriores incluidos como contexto +- **accountant**: Registros de libros contables (conocimiento) +- **secretary**: Registros de secretaría (conocimiento) ## Inmutabilidad +Ambas tablas: - **INSERT**: Permitido - **UPDATE**: Bloqueado por trigger - **DELETE**: Bloqueado por trigger ## Cadena de integridad -Cada mensaje referencia al anterior via `prev_hash`: - ``` msg1.hash = SHA256(msg1) msg2.prev_hash = msg1.hash msg2.hash = SHA256(msg2) -msg3.prev_hash = msg2.hash ... ``` @@ -47,14 +64,25 @@ Primer mensaje de sesión: `prev_hash = NULL` ## Índices -- `session_hash` - Buscar mensajes de una sesión -- `sender_id` - Mensajes enviados por un actor -- `receiver_id` - Mensajes recibidos por un actor -- `prev_hash` - Seguir cadena de integridad -- `created_at` - Ordenar cronológicamente -- `hashtags` (GIN) - Buscar por etiquetas +### log.messages +- `session_hash` - Mensajes de una sesión +- `thread_hash` - Mensajes de un hilo +- `sender_id` - Mensajes enviados +- `receiver_id` - Mensajes recibidos +- `prev_hash` - Cadena de integridad +- `created_at` - Orden cronológico +- `hashtags` (GIN) - Búsqueda por etiquetas + +### log.message_refs +- `message_hash` - Referencias de un mensaje +- `ref_hash` - Uso de una referencia +- `ref_type` - Filtrar por tipo +- `thread_hash` - Referencias de un hilo ## Relaciones externas -- `sender_id` y `receiver_id` referencian hashes de `core.players` -- `hashtags` referencian hashes de `core.hashtags` +- `sender_id`, `receiver_id`, `leader_id` → `core.players` +- `hashtags` → `core.hashtags` +- `ref_hash` (context) → `log.messages` +- `ref_hash` (accountant) → libros contables +- `ref_hash` (secretary) → registros secretaría diff --git a/schemas/04_log.sql b/schemas/04_log.sql index 11a076f..5939fb6 100644 --- a/schemas/04_log.sql +++ b/schemas/04_log.sql @@ -52,7 +52,7 @@ CREATE TABLE log.message_refs ( message_hash CHAR(64) NOT NULL, ref_hash CHAR(64) NOT NULL, ref_type log.ref_type NOT NULL, - position INT, + position INT NOT NULL, thread_hash CHAR(64), UNIQUE(message_hash, ref_hash) );