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

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).
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.