fn_registry/docs/functions.md

# Tabla: functions

Almacena funciones atómicas, pipelines y componentes React. Un pipeline es una función de `kind: pipeline`, siempre impura, que orquesta otras funciones del registry. Un componente es `kind: component` con campos adicionales para su API visual. Los tres comparten el mismo schema base.

---

## Campos base

| Campo | Tipo | Descripción | Notas / Restricciones |
|---|---|---|---|
| `id` | string | Identificador único generado. | Formato: `{name}_{lang}_{domain}` ej: `filter_slice_go_core`. UUID interno + slug legible. |
| `name` | string | Nombre de la función, pipeline o componente. | Obligatorio. Sin espacios, snake_case. |
| `kind` | enum | Clasificación del ejecutable. | `function` \| `pipeline` \| `component` |
| `lang` | enum | Lenguaje de implementación. | `go` \| `python` \| `sql` \| `typescript` \| ... (enum controlado, normalizado al indexar) |
| `domain` | string | Namespace o área de dominio. | Ej: `finance`, `dsp`, `core`, `io`. Evita colisiones de ID y filtra ruido en búsqueda. |
| `version` | string | Versión semántica de la función. | Semver: `1.0.0`. Permite detectar contratos rotos en `uses_functions`. |
| `purity` | enum | Indica si la función tiene side effects. | `pure` \| `impure` |
| `signature` | string | Firma completa incluyendo parámetros y tipos de retorno. | Para lenguajes sin tipos formales (Python sin hints), usar convención: `fn(xs: []T, pred: T→bool) → []T`. Para `kind: component`, es la interfaz de props en TypeScript/JSX. |
| `description` | text | Qué hace, por qué existe y cuándo usarla. | Obligatorio. |
| `tags` | []string | Etiquetas libres para búsqueda. | Dominio, patrón, utilidad. Ej: `[slice, functional, generic]` |
| `uses_functions` | []string | IDs de funciones del registry que esta función invoca. | Referencias validadas. `kind: pipeline` → no puede estar vacío. |
| `uses_types` | []string | IDs de tipos del registry que recibe como parámetros. | Referencias validadas contra tabla `types`. |
| `returns` | []string | IDs de tipos del registry que emite como resultado. | Referencias validadas. Vacío en `kind: component` — usar `emits`. |
| `returns_optional` | bool | Si el valor de retorno puede estar ausente. | Siempre `false` en puras. `true` en impuras que pueden no devolver valor. |
| `error_type` | string | ID del tipo de error que puede emitir. | Obligatorio en impuras. Referencia validada contra tabla `types`. |
| `imports` | []string | Dependencias externas fuera del registry. | Paquetes, módulos. Ej: `[github.com/shopspring/decimal]` |
| `example` | text | Ejemplo concreto de uso con inputs y outputs esperados. | Preferiblemente compilable. |
| `tested` | bool | Si existe al menos un test para esta función. | `true` → `test_file_path` obligatorio. |
| `tests` | []string | Lista de nombres o descripciones de los tests aplicados. | Vacío si `tested: false`. |
| `test_file_path` | string | Ruta relativa al archivo de test. | Relativa a la raíz del registry. Obligatoria si `tested: true`. |
| `file_path` | string | Ruta relativa al archivo de implementación. | Relativa a la raíz del registry. No rutas absolutas. |
| `created_at` | datetime | Fecha de creación de la entrada. | ISO 8601. Generado automáticamente. |
| `updated_at` | datetime | Fecha de última modificación. | ISO 8601. Actualizado automáticamente al indexar. |

---

## Campos adicionales — kind: component

Estos campos se añaden únicamente cuando `kind: component`. El resto del schema base aplica igual.

| Campo | Tipo | Descripción | Notas / Restricciones |
|---|---|---|---|
| `props` | []PropDef | API de entrada del componente. | Cada prop: `{ name, type, required, description }`. Equivale a los parámetros de una función. |
| `emits` | []string | Eventos que el componente lanza hacia arriba. | Ej: `[onClick, onChange, onSubmit]`. No son `returns` — son comunicación hacia el padre. |
| `has_state` | bool | Si el componente gestiona estado interno. | `true` → `purity: impure` automáticamente. `false` → puede ser `pure`. |
| `framework` | enum | Framework de UI en el que está implementado. | `react` (único valor registrado actualmente). Obligatorio en `kind: component`. |
| `variant` | []string | Variantes visuales o de comportamiento disponibles. | Ej: `[primary, ghost, danger, disabled]`. Útil para el agente al buscar una variante concreta. |

### Equivalencias function → component

| Concepto en functions | Equivalente en kind: component |
|---|---|
| parámetros de función | `props` — API de entrada con nombre, tipo y opcionalidad |
| `returns` | `emits` — eventos hacia el padre. `returns` queda vacío. |
| `purity: impure` | `has_state: true` → impure automáticamente |
| `signature` | Interfaz de props en TypeScript/JSX |
| `uses_types` | Tipos del registry usados en props o emits |

### Ejemplo de signature para un componente React

```tsx
DataTable<T>(props: { data: T[]; columns: ColumnDef<T>[]; onRowClick?: (row: T) => void }): JSX.Element
```

---

## Reglas de integridad

### Reglas base

| Condición | Regla |
|---|---|
| `kind: pipeline` | `purity` siempre `impure`. `uses_functions` no puede estar vacío. |
| `purity: pure` | `returns_optional` siempre `false`. `error_type` vacío. Una pura que devuelve opcional debe modelarse como tipo suma, no como `returns_optional: true`. |
| `purity: impure` | `error_type` obligatorio. Toda impura declara explícitamente qué puede salir mal. |
| `tested: true` | `test_file_path` obligatorio. `tests` no puede estar vacío. `fn index` extrae los test cases a la tabla `unit_tests` (ver [testing.md](testing.md)). |
| `tested: false` | `tests` vacío. `test_file_path` vacío. |
| `uses_functions[]` | Todos los IDs deben existir en la tabla `functions`. Sin referencias huérfanas. |
| `uses_types[]` | Todos los IDs deben existir en la tabla `types`. Sin referencias huérfanas. |
| `returns[]` | Todos los IDs deben existir en la tabla `types`. |
| `error_type` | Debe existir en la tabla `types` si informado. |
| `file_path` | Relativa a raíz del registry. Nunca absoluta. |
| `lang` | Debe pertenecer al enum controlado de lenguajes registrados. |
| `id` | Único global. Formato: `{name}_{lang}_{domain}`. Colisiones rechazadas. |

### Reglas adicionales — kind: component

| Condición | Regla |
|---|---|
| `kind: component` | `framework` obligatorio. |
| `kind: component` | `returns` vacío. Los outputs se expresan mediante `emits`. |
| `kind: component` | `signature` es la interfaz de props en formato TypeScript/JSX. |
| `has_state: false` + sin side effects | `purity: pure` válido. |
| `has_state: true` | `purity: impure` automáticamente. |
| `kind: component` | `uses_types` puede referenciar tipos del registry usados en props o emits. |