fn_registry/docs/fn_operations.md

# fn_operations — Schema de inteligencia operacional

Base de datos local por proyecto. Cada proyecto tiene su propio archivo `.db` independiente.
Referencia IDs del registry central (`fn_registry`) pero no los duplica — solo apunta a ellos.

---

## Propósito

El registry almacena **lo que sabes hacer**.
fn_operations almacena **lo que has hecho y cómo fluye** en un proyecto concreto.

| | fn_registry | fn_operations |
|---|---|---|
| **Naturaleza** | Conocimiento estático | Conocimiento dinámico |
| **Contenido** | Lo que sabes hacer | Lo que has hecho y cómo fluye |
| **Scope** | Compartida entre todos los proyectos | Local a cada proyecto — un `.db` por proyecto |
| **Tablas** | `functions`, `types` | `entities`, `relations`, `relation_inputs` |
| **Cuándo cambia** | Al añadir código al registry | En cada proyecto activo |

---

## Estructura de directorios

```
fn-registry/
  fn_operations/
    fn_operations.md       ← este archivo
    project_template/
      operations.db        ← plantilla vacía con schema y WAL mode aplicados
    migrations/
      001_init.sql         ← script de creación de tablas
```

---

## Tabla: entities

Una entity es una instancia concreta de un tipo del registry dentro del contexto de un proyecto.
No es el tipo en abstracto — es el dato real que fluye: `ticks_btcusdt_2024`, `ohlcv_1h_binance`, `user_session_web`.

El tipo del registry (`type_ref`) aporta conocimiento heredado — campos, estructura, semántica algebraica.
La entity aporta conocimiento contextual — qué rol juega aquí, de dónde viene, qué propiedades específicas tiene.

```
type_ref  → lo que la entidad ES       (heredado del registry)
metadata  → lo que la entidad TIENE    (específico de este contexto)
```

| Campo | Tipo | Descripción | Notas / Restricciones |
|---|---|---|---|
| `id` | string | Identificador único de la entidad en el proyecto. | Formato: `{name}_{context}` ej: `ticks_btcusdt_2024`. Único dentro del proyecto. |
| `name` | string | Nombre semántico de la entidad. | Descriptivo y específico al dominio del proyecto. Obligatorio. |
| `type_ref` | string | ID del tipo del registry que modela esta entidad. | Referencia a `types.id` en `fn_registry`. Obligatorio. |
| `status` | enum | Estado actual de la entidad. | `active` \| `stale` \| `corrupted` \| `archived` |
| `description` | text | Qué representa esta entidad en el contexto del proyecto. | No qué es el tipo en abstracto, sino qué rol juega aquí. |
| `domain` | string | Área de dominio dentro del proyecto. | Ej: `market_data`, `auth`, `reporting`. |
| `tags` | []string | Etiquetas libres para búsqueda y agrupación. | |
| `source` | string | Origen del dato. | Obligatorio. Ej: `binance_api`, `csv_upload`, `user_input`, `pipeline_output`. |
| `metadata` | json | Propiedades específicas del contexto no capturadas por el tipo. | Valores concretos de los campos del tipo. Ej: `{"pair":"BTCUSDT","exchange":"binance"}`. |
| `notes` | text | Contexto extra libre sobre la entidad. | Para el agente o para ti. Decisiones, observaciones, advertencias, historial informal. |
| `created_at` | datetime | Fecha de registro de la entidad. | ISO 8601. Generado automáticamente. |
| `updated_at` | datetime | Fecha de última modificación. | ISO 8601. Actualizado automáticamente. |

### Valores de status — entities

| Valor | Significado |
|---|---|
| `active` | Dato en uso, actualizado y fiable. |
| `stale` | Existe pero puede estar desactualizado. El agente debe verificar antes de usar. |
| `corrupted` | Se sabe que tiene problemas de integridad. No usar en pipelines. |
| `archived` | Ya no se usa activamente. Se conserva por trazabilidad histórica. |

### Reglas de integridad — entities

| Condición | Regla |
|---|---|
| `type_ref` | Debe existir en `fn_registry.types.id`. Sin referencias huérfanas. |
| `id` | Único dentro del proyecto. Formato `{name}_{context}`. |
| `source` | Obligatorio. Todo dato tiene un origen conocido. |
| `name` | Obligatorio. Sin espacios, snake_case. |
| `metadata` | JSON válido. Debe contener los valores de los campos definidos por el tipo del registry. |
| `status: corrupted` | El agente nunca debe usar esta entidad como input de una relation activa. |

---

## Tabla: relations

Una relation describe cómo una entidad se conecta o transforma en otra. Puede documentar una
transformación técnica a través de una función del registry, o una relación puramente semántica
sin función asociada. El campo `name` expresa el significado humano de la conexión.

```
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, agregaciones multi-fuente),
se usa la tabla `relation_inputs` en lugar de `from_entity`. Ver sección correspondiente.

| Campo | Tipo | Descripción | Notas / Restricciones |
|---|---|---|---|
| `id` | string | Identificador único de la relación. | Formato: `{from}__to__{to}__via__{fn}`. Legible sin joins. |
| `name` | string | Etiqueta semántica de la relación. | El verbo o concepto que describe la conexión. Ej: `CONOCE A`, `TRANSFORMA`, `PRODUCE`, `DEPENDE DE`. Obligatorio. |
| `from_entity` | string | ID de la entidad origen para relaciones simples (1-a-1). | Referencia a `entities.id`. Opcional si se usa `relation_inputs`. |
| `to_entity` | string | ID de la entidad destino. | Referencia a `entities.id`. Obligatorio. |
| `via` | string | ID de la función o pipeline del registry que realiza la transformación. | Referencia a `functions.id` en `fn_registry`. Opcional — vacío si la relación es puramente semántica. |
| `description` | text | Qué ocurre en esta conexión en el contexto del proyecto. | No qué hace la función en abstracto, sino qué significa aquí. |
| `purity` | enum | Naturaleza de la transformación. | `pure` \| `impure`. Si `via` está informado, debe ser consistente con `via.purity` en el registry. |
| `direction` | enum | Dirección semántica de la relación. | `unidirectional` \| `bidirectional` \| `inverse`. Ver valores abajo. |
| `weight` | float | Ponderación opcional de la relación. | Rango `0.0 – 1.0`. Permite queryar "relaciones con peso > 0.8". Opcional. |
| `status` | enum | Estado del flujo. | `designed` \| `implemented` \| `tested` \| `running` \| `deprecated` |
| `started_at` | datetime | Cuándo empezó el flujo realmente. | ISO 8601. Distinto de `created_at` — ese es cuándo lo documentaste. |
| `ended_at` | datetime | Cuándo terminó o dejó de ejecutarse el flujo. | ISO 8601. Vacío si sigue activo. |
| `order` | int | Posición en el pipeline si forma parte de una secuencia ordenada. | Opcional. Permite reconstruir el grafo en orden de ejecución. |
| `tags` | []string | Etiquetas libres. | |
| `notes` | text | Observaciones, decisiones de diseño, problemas conocidos. | Libre. El agente lee esto para entender contexto histórico del flujo. |
| `created_at` | datetime | Fecha de registro de la relación. | ISO 8601. Generado automáticamente. |
| `updated_at` | datetime | Fecha de última modificación. | ISO 8601. Actualizado automáticamente. |

### Valores de direction

| Valor | Significado |
|---|---|
| `unidirectional` | A → B. La relación fluye en un solo sentido. Valor por defecto. |
| `bidirectional` | A ↔ B. La relación es simétrica — vale en ambos sentidos. Ej: `CONOCE A`. |
| `inverse` | La relación se documenta de B a A pero su lectura natural es de A a B. Útil para linaje inverso. |

### Valores de status — relations

| Valor | Significado |
|---|---|
| `designed` | Flujo planificado. Existe en el grafo de arquitectura pero no hay código todavía. |
| `implemented` | Código escrito. No verificado en este contexto de proyecto aún. |
| `tested` | Verificado en este proyecto. Los datos fluyen correctamente. |
| `running` | Activo en producción o en uso continuo. |
| `deprecated` | Ya no se usa. Se mantiene por trazabilidad histórica. |

### Reglas de integridad — relations

| Condición | Regla |
|---|---|
| `name` | Obligatorio. Describe el verbo semántico de la relación. |
| `from_entity` | Si informado, debe existir en `entities.id`. Vacío si se usa `relation_inputs`. |
| `from_entity` o `relation_inputs` | Al menos uno de los dos debe estar presente. Una relation sin origen es inválida. |
| `to_entity` | Debe existir en `entities.id`. Obligatorio. |
| `via` | Si informado, debe existir en `fn_registry.functions.id`. |
| `purity` | Si `via` está informado, debe ser consistente con `via.purity` en el registry. |
| `weight` | Si informado, debe estar en el rango `0.0 – 1.0`. |
| `from_entity != to_entity` | Una entidad no puede relacionarse consigo misma. |
| `started_at` / `ended_at` | Si ambos informados, `started_at` debe ser anterior a `ended_at`. |
| `id` | Único dentro del proyecto. |
| **Sin ciclos** | El CLI valida al insertar que la nueva relation no crea un ciclo en el grafo. Si lo crea, la inserción se rechaza. SQLite no detecta ciclos — esta validación ocurre en la capa de aplicación. |

---

## Tabla: relation_inputs

Tabla intermedia para relaciones que consumen **múltiples entidades simultáneamente** — joins,
merges, agregaciones multi-fuente. Cuando una relation usa `relation_inputs`, el campo
`from_entity` en `relations` se deja vacío.

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

| Campo | Tipo | Descripción | Notas / Restricciones |
|---|---|---|---|
| `id` | string | Identificador único del input. | Generado automáticamente. |
| `relation_id` | string | ID de la relation a la que pertenece este input. | Referencia a `relations.id`. Obligatorio. |
| `entity_id` | string | ID de la entidad que actúa como input. | Referencia a `entities.id`. Obligatorio. |
| `role` | string | Rol semántico de este input en la relación. | Ej: `base`, `lookup`, `filter`, `left`, `right`. Obligatorio. Permite al agente entender cómo se usa cada input. |
| `order` | int | Orden del input si la relación es sensible al orden. | Opcional. Ej: en un join `left`/`right` el orden importa. |

### Reglas de integridad — relation_inputs

| Condición | Regla |
|---|---|
| `relation_id` | Debe existir en `relations.id`. |
| `entity_id` | Debe existir en `entities.id`. |
| `role` | Obligatorio. Sin rol el agente no puede razonar sobre cómo se usa el input. |
| Mínimo 2 inputs | Una relation con `relation_inputs` debe tener al menos 2 entradas. Si solo hay una, usar `from_entity` en su lugar. |

---

## Referencias cruzadas completas

| Campo origen | → | Destino |
|---|---|---|
| `entities.type_ref` | → | `fn_registry → types.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` |

---

## Ejemplo — pipeline de market data

### Entities

| id | type_ref | status | source | metadata |
|---|---|---|---|---|
| `ticks_btcusdt_2024` | `tick_go_finance` | `active` | `binance_api` | `{"pair":"BTCUSDT","exchange":"binance"}` |
| `metadata_binance` | `exchange_meta_go_finance` | `active` | `binance_api` | `{"version":"v3"}` |
| `ohlcv_1h_btcusdt` | `ohlcv_go_finance` | `active` | `pipeline_output` | `{"interval":"1h","pair":"BTCUSDT"}` |
| `sma_20_btcusdt` | `float64_slice_go_core` | `active` | `pipeline_output` | `{"period":20,"field":"close"}` |

### Relations simples

| name | from_entity | to_entity | via | direction | status | weight |
|---|---|---|---|---|---|---|
| `CALCULA` | `ohlcv_1h_btcusdt` | `sma_20_btcusdt` | `sma_go_finance` | `unidirectional` | `tested` | 1.0 |

### Relation con múltiples inputs (relation_inputs)

**Relation:** `id: ticks_y_meta__to__ohlcv__via__enrich`, `name: ENRIQUECE`, `to_entity: ohlcv_1h_btcusdt`

| relation_id | entity_id | role | order |
|---|---|---|---|
| `ticks_y_meta__to__ohlcv__via__enrich` | `ticks_btcusdt_2024` | `base` | 1 |
| `ticks_y_meta__to__ohlcv__via__enrich` | `metadata_binance` | `lookup` | 2 |

### Grafo resultante

```
[ticks_btcusdt_2024] ──┐
                        ├─ ENRIQUECE (impure · running) ──→ [ohlcv_1h_btcusdt]
[metadata_binance]   ──┘                                           ↓
                                                    CALCULA (pure · tested)
                                                           ↓
                                                   [sma_20_btcusdt]
```

---

## Ejemplo — relaciones semánticas puras (sin via)

```
[juan] (type: person)   →  CONOCE A   (bidirectional, weight: 0.9)  →  [paula]
[servicio_auth]         →  DEPENDE DE (unidirectional, weight: 1.0)  →  [bbdd_usuarios]
[modelo_riesgo]         →  ALIMENTA   (unidirectional, weight: 0.7)  →  [dashboard_trading]
```

---

## Escalabilidad

| Fase | BBDD | Cuándo migrar |
|---|---|---|
| Inicial | SQLite + WAL mode | Proyectos personales, un agente escribiendo |
| Crecimiento | PostgreSQL | Múltiples agentes escribiendo concurrentemente |
| Analítico | ClickHouse | Millones de operaciones, dashboards de uso |