docs: schema de documentacion v1.0

Añade la especificacion completa del registry: - README con overview de tablas y kinds - Schema de functions (atomicas, pipelines, components) - Schema de types (algebraicos: product y sum) - Reglas de integridad y referencias cruzadas - Arquitectura del sistema (registry vs operacional) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-28 01:59:14 +01:00
parent 2a55cd99dc
commit 1e4ffba40e
5 changed files with 403 additions and 0 deletions
@@ -0,0 +1,133 @@
+# Arquitectura del sistema
+
+---
+
+## Dos bases de datos, dos propósitos
+
+| | Registry (esta BBDD) | Operacional (por proyecto) |
+|---|---|---|
+| **Qué almacena** | Lo que sabes hacer | Lo que has hecho y cómo fluye |
+| **Naturaleza** | Conocimiento estático | Conocimiento dinámico |
+| **Cuándo cambia** | Solo al añadir código | En cada proyecto activo |
+| **Scope** | Compartida entre todos los proyectos | Local a cada proyecto |
+| **Tablas** | `functions`, `types` | `entities`, `relations` |
+
+---
+
+## Registry — estructura de directorios
+
+```
+fn-registry/
+  functions/
+    core/
+      filter_slice.go
+      filter_slice.md
+    finance/
+      parse_ohlcv.go
+      parse_ohlcv.md
+    io/
+      fetch_ticks.go
+      fetch_ticks.md
+    pipelines/
+      tick_to_ohlcv.go
+      tick_to_ohlcv.md
+    components/
+      DataTable.tsx
+      DataTable.md
+  types/
+    core/
+      result.go
+      result.md
+    finance/
+      ohlcv.go
+      ohlcv.md
+  registry.db       ← SQLite, solo índice FTS. Regenerable siempre.
+  fn                ← binario CLI
+```
+
+Los archivos `.go` / `.tsx` son la **fuente de verdad del código**.
+Los archivos `.md` son la **fuente de verdad de la documentación**.
+`registry.db` es solo el índice — si se borra, `fn index` lo regenera en segundos.
+
+---
+
+## CLI — comandos
+
+```bash
+fn search "filter predicate sin mutar"   # búsqueda FTS sobre nombre, descripción, tags, signature
+fn search -k function -p pure "slice"    # filtrar por kind y purity
+fn search -l go -d finance "ohlcv"       # filtrar por lang y domain
+fn search -k component "tabla datos"     # buscar componentes React
+
+fn add                                   # abre $EDITOR con template según kind
+fn show filter_slice_go_core             # imprime entrada completa
+fn index                                 # regenera registry.db desde los .md
+
+fn list                                  # lista todas las entradas
+fn list -d finance                       # lista por dominio
+fn list -k pipeline                      # lista solo pipelines
+```
+
+---
+
+## Operacional — tablas por proyecto
+
+Cada proyecto tiene su propia BBDD operacional que referencia IDs del registry.
+
+### Entities
+
+Instancias concretas de tipos registrados dentro de un contexto de ejecución.
+
+| Campo | Tipo | Descripción |
+|---|---|---|
+| `id` | string | Identificador único |
+| `name` | string | Nombre semántico (`ticks_btcusdt`) |
+| `type_ref` | string | Referencia al `types.id` del registry |
+| `description` | text | Qué representa en este dominio concreto |
+| `tags` | []string | Etiquetas |
+
+### Relations
+
+Cómo las entidades se conectan a través de funciones o pipelines.
+
+| Campo | Tipo | Descripción |
+|---|---|---|
+| `id` | string | Identificador único |
+| `from_entity` | string | Entidad origen |
+| `to_entity` | string | Entidad destino |
+| `via` | string | `functions.id` que transforma |
+| `description` | text | Qué ocurre en esta transformación |
+| `purity` | enum | `pure` \| `impure` |
+
+---
+
+## El agente y el registry
+
+El agente consulta el registry para:
+
+1. **Descubrir** qué funciones y tipos existen en un dominio
+2. **Razonar** sobre composabilidad comparando `returns` con `uses_types`
+3. **Priorizar** funciones puras para el núcleo del pipeline
+4. **Aislar** impuras en los bordes
+5. **Verificar** que los contratos no están rotos comparando `version`
+
+El agente consulta la operacional para:
+
+1. Entender qué entidades fluyen en este proyecto concreto
+2. Ver qué transformaciones ya están modeladas
+3. Detectar patrones de uso frecuentes
+
+---
+
+## Mejoras incorporadas al schema v1.0
+
+| Problema | Solución |
+|---|---|
+| IDs frágiles con colisiones | Formato `{name}_{lang}_{domain}` + UUID interno |
+| `lang` libre fragmenta el índice | Enum controlado, normalizado al indexar |
+| Sin versionado | Campo `version` semver en functions y types |
+| `file_path` absoluta se rompe al mover | Siempre relativa a la raíz del registry |
+| Sin contexto de dominio | Campo `domain` obligatorio |
+| Sin trazabilidad temporal | `created_at` / `updated_at` automáticos |
+| `signature` ambigua en lenguajes dinámicos | Convención formal definida para Python/SQL |
+| Pura que devuelve opcional mal modelada | Regla: modelar como tipo suma, no `returns_optional: true` |