fn_registry/.claude/CLAUDE.md

# fn-registry

Registry personal de codigo reutilizable con busqueda FTS. Diseñado para composicion funcional y agentes.

**Dos bases de datos SQLite:**
- **registry.db** (raiz) — funciones, tipos, proposals. Regenerable con `fn index` (excepto proposals).
- **operations.db** (por app en `apps/*/`) — entities, relations, executions, assertions. Datos vivos.

**Reglas y convenciones:** ver `.claude/rules/INDEX.md`

---

## Explorar el registry (USAR SIEMPRE)

Antes de escribir codigo, SIEMPRE consulta registry.db para evitar duplicados y descubrir funciones reutilizables.

```bash
# FTS5
sqlite3 registry.db "SELECT id, kind, purity, description FROM functions WHERE id IN (SELECT id FROM functions_fts WHERE functions_fts MATCH 'slice') ORDER BY name;"

# Por dominio
sqlite3 registry.db "SELECT id, purity, signature FROM functions WHERE domain = 'finance' ORDER BY name;"

# Puras de un dominio
sqlite3 registry.db "SELECT id, signature FROM functions WHERE domain = 'core' AND purity = 'pure' ORDER BY name;"

# Tipos
sqlite3 registry.db "SELECT id, algebraic, description FROM types WHERE domain = 'cybersecurity';"

# Dependencias
sqlite3 registry.db "SELECT id, uses_functions, uses_types FROM functions WHERE uses_functions != '[]';"

# Proposals pendientes
sqlite3 registry.db "SELECT id, kind, status, title FROM proposals WHERE status = 'pending';"

# Schema completo
sqlite3 registry.db ".schema"
```

---

## Estructura

```
fn-registry/
  functions/{domain}/     # .go + .md por funcion (core, finance, datascience, cybersecurity)
  functions/pipelines/    # Composiciones, siempre impuras
  functions/components/   # React (.tsx)
  types/{domain}/         # .go + .md por tipo
  registry/               # Paquete Go: modelos, SQLite, parser, indexer, validacion, migraciones
  fn_operations/          # Paquete Go: operations database (libreria)
  apps/                   # Apps ejecutables (TUIs, CLIs) — modulos Go independientes, cada una con su operations.db
  cmd/fn/                 # CLI principal
  docs/                   # Specs de diseño
  docs/templates/         # Plantillas de frontmatter
```

---

## Build

```bash
CGO_ENABLED=1 go build -tags fts5 -o fn ./cmd/fn/
CGO_ENABLED=1 go test -tags fts5 ./...
```

---

## CLI

```bash
# Registry
fn index                            # Regenera registry.db
fn search "texto"                   # FTS en functions + types
fn search -k function -p pure -d core "slice"
fn list [-d domain] [-k kind]
fn show <id>
fn add -k function                  # Template

# Proposals
fn proposal add --kind new_function --title "..." --created-by agent [--target-id <id>]
fn proposal list [-k kind] [-s status]
fn proposal show <id>
fn proposal update <id> --status approved [--reviewed-by lucas]

# Operations (desde directorio con operations.db)
fn ops init [path]
fn ops entity add|list|show|delete
fn ops relation add|list|show|delete
fn ops graph
fn ops snapshot list|check|update
fn ops execution add|list|show
fn ops assertion add|list|show|delete|eval [--react]
fn ops assertion result add|list
```

`FN_REGISTRY_ROOT` env var permite que `fn ops` acceda a registry.db desde cualquier directorio.

---

## Añadir funciones

1. Consulta la BD para verificar que no existe algo similar
2. Crea dos archivos: `functions/{domain}/{name}.go` + `functions/{domain}/{name}.md`
3. Ejecuta `./fn index` y verifica con `./fn show {id}`

Frontmatter del .md — ver template completo en `docs/templates/` o con `fn add -k function`.

Reglas de integridad (el indexer las valida):
- Pipeline → siempre impuro + uses_functions no vacio
- Pure → returns_optional: false + error_type: ""
- Impure → error_type obligatorio (usar `error_go_core`)
- tested: true → test_file_path y tests obligatorios
- uses_functions, uses_types, returns, error_type → IDs existentes
- Component → framework obligatorio, returns vacio (usar emits)
- file_path siempre relativa, IDs formato `{name}_{lang}_{domain}`
- Campo `returns` solo para IDs del registry, NO tipos nativos de Go

## Añadir tipos

Dos archivos: `types/{domain}/{name}.go` + `types/{domain}/{name}.md`. Ver template en `docs/templates/`.

---

## Bucle reactivo: CONSTRUIR → EJECUTAR → RECOPILAR → ANALIZAR → MEJORAR

### 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 nucleo, aisla impuras en los bordes.
- Registra el pipeline en operations como `status: designed → implemented`.
- **BD:** `registry.db` (functions, types) → `operations.db` (relations, entities)

### 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.
- **BD:** `operations.db` (executions, relations)

### 3. RECOPILAR
- Entities se pueblan — `metadata` contiene los valores concretos de los campos del tipo.
- `types_snapshot` garantiza que `operations.db` es autonomo sin `registry.db`.
- El agente actualiza `entity.status` segun los datos recibidos.
- **BD:** `operations.db` (entities, types_snapshot)

### 4. ANALIZAR
- Agente evalua todas las `assertions` activas sobre las entities producidas.
- Compara `metrics` de la ejecucion actual con `executions` historicas.
- `critical` falla → `entity.status = corrupted`.
- `warning` falla → `entity.status = stale`.
- Resultados en `assertion_results` con `value` concreto para debugging.
- **BD:** `operations.db` (assertions, assertion_results, entities.status)

### 5. MEJORAR
- Si assertions fallan o metricas 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.
- **BD:** `registry.db` (proposals)

Codigo: `ExecuteAndReact()` en `fn_operations/operations.go` ejecuta pasos 2-4.
CLI: `fn ops assertion eval --entity-id X --react` ejecuta pasos 4-5.
Las assertion rules son expresiones SQL. Campos sin prefijo se reescriben a `json_extract(metadata, '$.campo')`.

---

## Fuentes de verdad

| Que | Donde |
|---|---|
| Codigo | .go / .py / .tsx |
| Metadata | .md junto al codigo |
| Schema de BDs | `sqlite3 *.db ".schema"` o `docs/` |
| Indice | registry.db (`fn index`) |
| Proposals, entities, executions, assertions | datos vivos en sus BDs |