fn_registry/docs/fn-registry-system-complete.md

# fn-registry — Sistema de conocimiento componible para agentes autónomos

Schema completo · Bucle autónomo · Optimizaciones para agentes

---

## Visión general del sistema

| | fn_registry | fn_operations |
|---|---|---|
| **Naturaleza** | Conocimiento estático | Conocimiento dinámico |
| **Pregunta** | ¿Qué existe y qué puedo hacer? | ¿Qué ha ocurrido y cómo se conecta? |
| **Tablas** | `functions` · `types` · `proposals` | `entities` · `relations` · `relation_inputs` · `types_snapshot` · `executions` · `assertions` · `assertion_results` |
| **Scope** | Compartido entre todos los proyectos | Local a cada proyecto — un `.db` por proyecto |
| **Ontología** | Intensional — define conceptos en abstracto | Extensional — instancias concretas con valores reales |

---

## REGISTRY

### Tabla: functions

Almacena funciones atómicas, pipelines y componentes React. Un pipeline es `kind: pipeline`, siempre impuro, que orquesta otras funciones. Un componente es `kind: component` con campos adicionales para su API visual.

| Campo | Tipo | Descripción | Notas / Restricciones |
|---|---|---|---|
| `id` | string | Identificador único. | Formato: `{name}_{lang}_{domain}` ej: `filter_slice_go_core` |
| `name` | string | Nombre de la función o pipeline. | Obligatorio. snake_case. |
| `kind` | enum | Clasificación. | `function` \| `pipeline` \| `component` |
| `lang` | enum | Lenguaje. | `go` \| `python` \| `sql` \| `typescript` \| ... |
| `domain` | string | Namespace de dominio. | `finance`, `dsp`, `core`, `io`... |
| `version` | string | Versión semántica. | Semver: `1.0.0` |
| `purity` | enum | Side effects. | `pure` \| `impure` |
| `signature` | string | Firma completa. | Con parámetros y tipos de retorno. |
| `description` | text | Qué hace, por qué existe, cuándo usarla. | Obligatorio. |
| `tags` | []string | Etiquetas de búsqueda. | |
| `uses_functions` | []string | Funciones del registry que invoca. | IDs validados. |
| `uses_types` | []string | Tipos que recibe como parámetros. | IDs validados. |
| `returns` | []string | Tipos que emite. | IDs validados. |
| `returns_optional` | bool | Si el retorno puede estar ausente. | Siempre `false` en puras. |
| `error_type` | string | Tipo de error que puede emitir. | Obligatorio en impuras. |
| `imports` | []string | Dependencias externas. | |
| `example` | text | Ejemplo de uso. | Preferiblemente compilable. |
| `tested` | bool | Si tiene test. | `true` → `test_file_path` obligatorio. |
| `tests` | []string | Lista de tests aplicados. | |
| `test_file_path` | string | Ruta al archivo de test. | Relativa a raíz del registry. |
| `file_path` | string | Ruta al archivo de implementación. | Relativa a raíz del registry. |
| `created_at` | datetime | Fecha de creación. | ISO 8601. Automático. |
| `updated_at` | datetime | Fecha de última modificación. | ISO 8601. Automático. |

#### Campos adicionales — kind: component

| Campo | Tipo | Descripción | Notas / Restricciones |
|---|---|---|---|
| `props` | []PropDef | API de entrada. | `{ name, type, required, description }` |
| `emits` | []string | Eventos hacia el padre. | Ej: `[onClick, onChange]`. No son `returns`. |
| `has_state` | bool | Gestiona estado interno. | `true` → `purity: impure` automáticamente. |
| `framework` | enum | Framework de UI. | `react`. Obligatorio en `kind: component`. |
| `variant` | []string | Variantes disponibles. | Ej: `[primary, ghost, danger]` |

#### Reglas de integridad — functions

| Condición | Regla |
|---|---|
| `kind: pipeline` | `purity` siempre `impure`. `uses_functions` no puede estar vacío. |
| `kind: component` | `framework` obligatorio. `returns` vacío — usar `emits`. |
| `purity: pure` | `returns_optional: false`. `error_type` vacío. Una pura que devuelve opcional debe modelarse como tipo suma. |
| `purity: impure` | `error_type` obligatorio. |
| `tested: true` | `test_file_path` y `tests` obligatorios. |
| `uses_functions[]` | Todos los IDs deben existir en `functions`. |
| `uses_types[]` | Todos los IDs deben existir en `types`. |
| `has_state: true` | `purity: impure` automáticamente en componentes. |

---

### Tabla: types

Los tipos son el contrato entre funciones. Permiten al agente razonar sobre composabilidad sin leer implementaciones.

**Tipo producto** — todos los campos siempre presentes. Modela datos y entidades. Valores posibles = N₁ × N₂ × ... × Nₙ

**Tipo suma** — un caso activo a la vez. Modela estados, resultados y alternativas. Valores posibles = N₁ + N₂ + ... + Nₙ

| Campo | Tipo | Descripción | Notas / Restricciones |
|---|---|---|---|
| `id` | string | Identificador único. | Formato: `{name}_{lang}_{domain}` ej: `ohlcv_go_finance` |
| `name` | string | Nombre del tipo. | PascalCase recomendado. |
| `lang` | enum | Lenguaje. | Mismo enum que `functions`. |
| `domain` | string | Namespace de dominio. | |
| `version` | string | Versión semántica. | Semver: `1.0.0` |
| `algebraic` | enum | Categoría algebraica. | `product` \| `sum` |
| `definition` | text | Definición completa. | Código real. |
| `description` | text | Qué modela y cuándo usarlo. | Obligatorio. |
| `tags` | []string | Etiquetas de búsqueda. | |
| `uses_types` | []string | Tipos que compone internamente. | IDs validados. |
| `file_path` | string | Ruta al archivo. | Relativa a raíz del registry. |
| `created_at` | datetime | Fecha de creación. | ISO 8601. Automático. |
| `updated_at` | datetime | Fecha de última modificación. | ISO 8601. Automático. |

#### Reglas de integridad — types

| Condición | Regla |
|---|---|
| `algebraic: product` | Todos los campos siempre presentes. Modela datos. |
| `algebraic: sum` | Un caso activo a la vez. Modela estados y resultados. |
| `uses_types[]` | Solo IDs existentes. Sin auto-referencias. |

---

### Tabla: proposals

El agente escribe propuestas de mejora al registry cuando assertions fallan o métricas son pobres. El humano revisa y aprueba. El registry crece de forma controlada.

Las proposals viven en **registry** — no en operations — porque su destino es el conocimiento estático compartido entre todos los proyectos.

```
operations  →  detecta el problema     (assertions, assertion_results)
registry    →  propuesta de solución   (proposals) — beneficia a todos los proyectos
```

| Campo | Tipo | Descripción | Notas / Restricciones |
|---|---|---|---|
| `id` | string | Identificador único. | |
| `kind` | enum | Tipo de propuesta. | `new_function` \| `new_type` \| `improve_function` \| `improve_type` \| `new_pipeline` |
| `target_id` | string | ID del elemento a mejorar si aplica. | Vacío para propuestas nuevas. Referencia a `functions.id` o `types.id`. |
| `title` | string | Título corto. | Obligatorio. |
| `description` | text | Qué propone y por qué. | El agente explica su razonamiento. |
| `evidence` | json | Datos que justifican la propuesta. | Ej: `assertion_ids` que fallaron, métricas de `executions`. |
| `status` | enum | Estado de revisión. | `pending` \| `approved` \| `rejected` \| `implemented` |
| `created_by` | string | Quién propone. | Ej: `agent`, `human`. |
| `reviewed_by` | string | Quién revisó. | Vacío si `pending`. |
| `created_at` | datetime | Fecha de la propuesta. | ISO 8601. |
| `updated_at` | datetime | Fecha de última modificación. | ISO 8601. |

---

## OPERATIONS

### Tabla: entities

Una entity es una instancia concreta de un tipo del registry dentro del contexto de un proyecto.

```
type_ref  →  lo que la entidad ES       (heredado del registry)
metadata  →  valores concretos del tipo (la instancia real)
```

| Campo | Tipo | Descripción | Notas / Restricciones |
|---|---|---|---|
| `id` | string | Identificador único en el proyecto. | Formato: `{name}_{context}` ej: `ticks_btcusdt_2024` |
| `name` | string | Nombre semántico. | Obligatorio. snake_case. |
| `type_ref` | string | ID del tipo del registry. | Referencia a `types.id`. Obligatorio. |
| `status` | enum | Estado actual. | `active` \| `stale` \| `corrupted` \| `archived` |
| `description` | text | Rol en el contexto del proyecto. | |
| `domain` | string | Área de dominio. | Ej: `market_data`, `auth`. |
| `tags` | []string | Etiquetas de búsqueda. | |
| `source` | string | Origen del dato. | Obligatorio. Ej: `binance_api`, `pipeline_output`. |
| `metadata` | json | Valores concretos de los campos del tipo. | Ej: si `type_ref` es `person_go_core` con campos `name` y `dni`, aquí va `{"name":"Juan","dni":"32435"}`. Es la instancia real del tipo. |
| `notes` | text | Contexto extra libre. | Para el agente o para ti. |
| `created_at` | datetime | Fecha de registro. | ISO 8601. Automático. |
| `updated_at` | datetime | Fecha de modificación. | ISO 8601. Automático. |

#### Valores de status — entities

| Valor | Significado |
|---|---|
| `active` | Dato en uso, actualizado y fiable. |
| `stale` | Puede estar desactualizado. El agente verifica antes de usar. |
| `corrupted` | Problemas de integridad. El agente no lo usa como input en ningún pipeline activo. |
| `archived` | Ya no se usa. Se conserva por trazabilidad histórica. |

#### Reglas de integridad — entities

| Condición | Regla |
|---|---|
| `type_ref` | Debe existir en `fn_registry.types.id` o en `types_snapshot.id`. |
| `source` | Obligatorio. Todo dato tiene un origen conocido. |
| `metadata` | JSON válido. Contiene los valores de los campos definidos por el tipo del registry. |
| `status: corrupted` | El agente nunca usa esta entity como input de una relation activa. |

---

### Tabla: types_snapshot

Copia local de los tipos del registry en el momento de su primer uso. Hace `operations.db` completamente autónomo — no necesita `registry.db` en runtime ni en producción.

| Campo | Tipo | Descripción | Notas / Restricciones |
|---|---|---|---|
| `id` | string | ID original del tipo en el registry. | |
| `version` | string | Versión en el momento del snapshot. | Semver. Inmutable tras el snapshot. |
| `lang` | string | Lenguaje. | |
| `algebraic` | enum | `product` \| `sum`. | |
| `definition` | text | Definición copiada. | Inmutable. |
| `description` | text | Descripción copiada. | Inmutable. |
| `snapped_at` | datetime | Cuándo se hizo el snapshot. | ISO 8601. Automático. |

---

### Tabla: relations

Describe cómo una entidad se conecta o transforma en otra. El campo `name` expresa el significado humano de la conexión. `via` es opcional — vacío para relaciones puramente semánticas.

```
juan (type: person)  →  CONOCE A  →  paula (type: person)
ticks                →  AGREGA    →  ohlcv_1h   (via: tick_to_ohlcv_go_finance)
```

Para relaciones que consumen múltiples entidades (joins, merges) se usa `relation_inputs` en lugar de `from_entity`.

| Campo | Tipo | Descripción | Notas / Restricciones |
|---|---|---|---|
| `id` | string | Identificador único. | Formato: `{from}__to__{to}__via__{fn}` |
| `name` | string | Etiqueta semántica de la relación. | Ej: `CONOCE A`, `TRANSFORMA`, `PRODUCE`, `DEPENDE DE`. Obligatorio. |
| `from_entity` | string | Entidad origen para relaciones 1-a-1. | Opcional si se usa `relation_inputs`. |
| `to_entity` | string | Entidad destino. | Obligatorio. |
| `via` | string | Función del registry que transforma. | Opcional — vacío si relación semántica. |
| `description` | text | Qué ocurre en este contexto. | |
| `purity` | enum | Naturaleza de la transformación. | `pure` \| `impure`. Consistente con `via.purity` si informado. |
| `direction` | enum | Dirección semántica. | `unidirectional` \| `bidirectional` \| `inverse` |
| `weight` | float | Ponderación opcional. | Rango `0.0 – 1.0`. |
| `status` | enum | Estado del flujo. | `designed` \| `implemented` \| `tested` \| `running` \| `deprecated` |
| `started_at` | datetime | Cuándo empezó el flujo realmente. | Distinto de `created_at`. |
| `ended_at` | datetime | Cuándo terminó. | Vacío si sigue activo. |
| `order` | int | Posición en secuencia. | Opcional. |
| `tags` | []string | Etiquetas. | |
| `notes` | text | Observaciones y contexto histórico. | El agente lee esto. |
| `created_at` | datetime | Fecha de documentación. | ISO 8601. Automático. |
| `updated_at` | datetime | Fecha de modificación. | ISO 8601. Automático. |

#### Valores de direction

| Valor | Significado |
|---|---|
| `unidirectional` | A → B. Un solo sentido. Valor por defecto. |
| `bidirectional` | A ↔ B. Simétrica. Ej: `CONOCE A`. |
| `inverse` | Documentada de B a A, lectura natural A a B. Para linaje inverso. |

#### Valores de status — relations

| Valor | Significado |
|---|---|
| `designed` | Planificado. En arquitectura pero sin código. |
| `implemented` | Código escrito. No verificado aún. |
| `tested` | Verificado. Los datos fluyen correctamente. |
| `running` | Activo en producción. |
| `deprecated` | Ya no se usa. Se mantiene por trazabilidad. |

#### Reglas de integridad — relations

| Condición | Regla |
|---|---|
| `name` | Obligatorio. |
| `from_entity` o `relation_inputs` | Al menos uno presente. Una relation sin origen es inválida. |
| `via` | Si informado, debe existir en `fn_registry.functions.id`. |
| `weight` | Si informado, rango `0.0 – 1.0`. |
| `started_at` / `ended_at` | Si ambos informados, `started_at` anterior a `ended_at`. |
| **Sin ciclos causales** | El CLI valida ciclos solo en relations con `via` informado. Las relaciones semánticas sin `via` pueden ser bidireccionales libremente. |

---

### Tabla: relation_inputs

Para relaciones que consumen múltiples entidades simultáneamente — joins, merges, agregaciones multi-fuente. Cuando se usa esta tabla, `from_entity` en `relations` se deja vacío.

```
join(ticks_btcusdt, metadata_binance)  →  ENRIQUECE  →  ohlcv_enriquecido
     ↑ role: "base"    ↑ role: "lookup"
```

| Campo | Tipo | Descripción | Notas / Restricciones |
|---|---|---|---|
| `id` | string | Identificador único. | Automático. |
| `relation_id` | string | Relation a la que pertenece. | Referencia a `relations.id`. Obligatorio. |
| `entity_id` | string | Entidad que actúa como input. | Referencia a `entities.id`. Obligatorio. |
| `role` | string | Rol semántico en la relación. | Ej: `base`, `lookup`, `filter`, `left`, `right`. Obligatorio. |
| `order` | int | Orden si la relación es sensible al orden. | Opcional. |

#### Reglas de integridad — relation_inputs

| Condición | Regla |
|---|---|
| `role` | Obligatorio. Sin rol el agente no puede razonar sobre cómo se usa el input. |
| Mínimo 2 inputs | Si se usa esta tabla, al menos 2 entradas. Si hay una sola usar `from_entity`. |

---

### Tabla: executions

Registra cada ejecución de un pipeline. Es la memoria de comportamiento del sistema — el agente consulta `executions` para detectar degradación, comparar rendimiento histórico y justificar `proposals`.

| Campo | Tipo | Descripción | Notas / Restricciones |
|---|---|---|---|
| `id` | string | Identificador único. | Automático. |
| `pipeline_id` | string | Función/pipeline ejecutado. | Referencia a `functions.id` en registry. |
| `relation_id` | string | Relation que disparó la ejecución. | Referencia a `relations.id`. |
| `status` | enum | Resultado. | `success` \| `failure` \| `partial` |
| `started_at` | datetime | Inicio real de la ejecución. | ISO 8601. |
| `ended_at` | datetime | Fin de la ejecución. | ISO 8601. |
| `duration_ms` | int | Duración en milisegundos. | |
| `records_in` | int | Registros de entrada procesados. | |
| `records_out` | int | Registros de salida producidos. | |
| `error` | text | Mensaje de error si falló. | Vacío si `success`. |
| `metrics` | json | Métricas clave del output. | Ej: `{"mean_close":42000,"nulls":0}` |
| `created_at` | datetime | Fecha de registro. | ISO 8601. Automático. |

---

### Tabla: assertions

Reglas de calidad formales sobre entities. Condiciones computables que el agente evalúa automáticamente tras cada ejecución. No texto libre — condiciones que devuelven `pass` o `fail`.

| Campo | Tipo | Descripción | Notas / Restricciones |
|---|---|---|---|
| `id` | string | Identificador único. | Ej: `ohlcv_close_positive` |
| `entity_id` | string | Entity sobre la que aplica. | Referencia a `entities.id`. |
| `name` | string | Nombre legible. | Ej: `close debe ser positivo` |
| `kind` | enum | Tipo de assertion. | `range` \| `null` \| `statistical` \| `consistency` \| `freshness` |
| `rule` | text | Condición formal evaluable. | SQL o expresión. Ej: `close > 0 AND close < open * 3` |
| `severity` | enum | Qué ocurre si falla. | `critical` \| `warning` \| `info` |
| `description` | text | Por qué existe esta regla. | Conocimiento de dominio que la justifica. |
| `active` | bool | Si se evalúa en cada ejecución. | Permite desactivar sin borrar. |
| `created_at` | datetime | Fecha de creación. | ISO 8601. |

#### Tipos de assertion

| Kind | Descripción y ejemplo |
|---|---|
| `range` | El valor debe estar dentro de un rango. Ej: `close BETWEEN 0 AND 1000000` |
| `null` | El campo no puede ser nulo. Ej: `open IS NOT NULL` |
| `statistical` | No debe desviarse más de N desviaciones estándar. Ej: `zscore(close) < 3` |
| `consistency` | Relación entre campos del mismo registro. Ej: `low <= close AND close <= high` |
| `freshness` | Los datos no pueden ser más antiguos de X. Ej: `max(ts) > now() - 1h` |

#### Lógica de severidad

| Severidad | Acción automática |
|---|---|
| `critical` | `entity.status = corrupted`. El agente no usa esta entity. Escribe en `proposals`. |
| `warning` | `entity.status = stale`. El agente la usa con precaución y lo documenta. |
| `info` | No cambia `status`. Solo registra en `assertion_results` para análisis histórico. |

---

### Tabla: assertion_results

Historial de cada evaluación de assertion. Permite al agente detectar tendencias — "esta assertion falla el 20% de las veces en ejecuciones nocturnas".

| Campo | Tipo | Descripción | Notas / Restricciones |
|---|---|---|---|
| `id` | string | Identificador único. | |
| `assertion_id` | string | Assertion evaluada. | Referencia a `assertions.id`. |
| `execution_id` | string | Ejecución que disparó la evaluación. | Referencia a `executions.id`. |
| `status` | enum | Resultado. | `pass` \| `fail` \| `skip` |
| `value` | json | Valor concreto evaluado. | Lo que tenía el dato cuando falló. |
| `message` | text | Descripción del fallo. | Generado automáticamente. |
| `evaluated_at` | datetime | Cuándo se evaluó. | ISO 8601. |

---

## El bucle autónomo

El sistema completo habilita un ciclo de mejora continua donde el agente construye, ejecuta, analiza y propone mejoras sin intervención humana salvo en la aprobación final.

### 1. CONSTRUIR
- Agente consulta registry → recupera funciones testeadas por FTS sobre `name`, `description`, `tags`.
- Razona sobre composabilidad comparando `returns` con `uses_types`.
- Prioriza funciones puras para el núcleo, aísla impuras en los bordes.
- Registra el pipeline en operations como `status: designed → implemented`.

### 2. EJECUTAR
- Pipeline corre → inserta registro en `executions` con `duration_ms`, `records_in`, `records_out`, `metrics`.
- `operations.relations.status = running`.
- Si falla → `execution.status = failure`, `error` capturado.

### 3. RECOPILAR
- Entities se pueblan — `metadata` contiene los valores concretos de los campos del tipo.
- `types_snapshot` garantiza que `operations.db` es autónomo sin `registry.db`.
- El agente actualiza `entity.status` según los datos recibidos.

### 4. ANALIZAR
- Agente evalúa todas las `assertions` activas sobre las entities producidas.
- Compara `metrics` de la ejecución actual con `executions` históricas.
- `critical` falla → `entity.status = corrupted`.
- `warning` falla → `entity.status = stale`.
- Resultados en `assertion_results` con `value` concreto para debugging.

### 5. MEJORAR
- Si assertions fallan o métricas degradan → agente escribe en `proposals`.
- `proposals.evidence` referencia los `assertion_ids` y `execution_ids` que lo justifican.
- El humano revisa `proposals.status: pending → approved → implemented`.
- El registry crece de forma controlada y trazable.

### 6. REPEAT
- Con el registry mejorado el agente construye mejor en la siguiente iteración.
- Cada ciclo acumula conocimiento — funciones más robustas, tipos más precisos, assertions más finas.
- El sistema mejora continuamente sin resetear el contexto acumulado.

---

## Optimizaciones para el agente

| Área | Mejora | Beneficio para el agente |
|---|---|---|
| Búsqueda en registry | Índice FTS5 sobre `name + description + tags + signature` | Recuperación en <5ms sin embeddings |
| `types_snapshot` | Copiar tipo completo al primer uso | `operations.db` completamente autónomo sin `registry.db` |
| Ciclos en grafo | Validar solo relations con `via` informado (causales) | Relaciones semánticas bidireccionales permitidas |
| `assertions` | Evaluar automáticamente tras cada `execution` | Agente detecta degradación sin intervención humana |
| `metadata` en entities | Almacenar instancia real del tipo como JSON | Agente lee valores sin acceder a ficheros externos |
| `proposals.evidence` | Referenciar `assertion_ids` y `execution_ids` concretos | Trazabilidad completa del razonamiento del agente |
| WAL mode SQLite | Activado por defecto en plantilla | Lectura simultánea mientras el agente escribe |
| `version` en `functions` y `types` | Semver explícito | Detección automática de contratos rotos |
| `direction` en relations | `unidirectional / bidirectional / inverse` | Agente recorre linaje hacia adelante y hacia atrás |
| `proposals` en registry | No en operations | Un solo punto de revisión humana para todos los proyectos |

---

## Referencias cruzadas completas

| Campo origen | → | Destino |
|---|---|---|
| `functions.uses_functions[]` | → | `functions.id` |
| `functions.uses_types[]` | → | `types.id` |
| `functions.returns[]` | → | `types.id` |
| `functions.error_type` | → | `types.id` |
| `types.uses_types[]` | → | `types.id` |
| `proposals.target_id` | → | `functions.id` o `types.id` (opcional) |
| `entities.type_ref` | → | `fn_registry → types.id` / `types_snapshot.id` |
| `relations.from_entity` | → | `entities.id` (opcional) |
| `relations.to_entity` | → | `entities.id` |
| `relations.via` | → | `fn_registry → functions.id` (opcional) |
| `relation_inputs.relation_id` | → | `relations.id` |
| `relation_inputs.entity_id` | → | `entities.id` |
| `executions.pipeline_id` | → | `fn_registry → functions.id` |
| `executions.relation_id` | → | `relations.id` |
| `assertions.entity_id` | → | `entities.id` |
| `assertion_results.assertion_id` | → | `assertions.id` |
| `assertion_results.execution_id` | → | `executions.id` |