syntaxis/docs/provision/current-state-analysis.md

# 📊 ANÁLISIS DEL ESTADO ACTUAL

**Fecha**: 2025-11-20
**Propósito**: Evaluación objetiva de qué existe realmente hoy
**Estado**: Revisión crítica (sin generar nuevas propuestas)

---

## 🎯 Diagrama ACTUAL (No Ideal)

```
┌─────────────────────────────────────────────────────────────┐
│ SYNTAXIS (Rust monorepository)                              │
│ ─────────────────────────────────────────────────────────── │
│                                                              │
│ /Users/Akasha/Development/syntaxis/                         │
│ └── configs/services-catalog.toml  ← SOURCE OF TRUTH ACTUAL │
│     - 6 servicios definidos en TOML                         │
│     - 4 patrones de deployment                              │
│     - 6 grupos de servicios                                 │
│     - Puertos y networking config                           │
│                                                              │
│ core/crates/syntaxis-core/                                  │
│ └── src/persistence/ [TODO: search for catalog usage]       │
│                                                              │
│ core/crates/cli/                                            │
│ └── CONSUME: configs/services-catalog.toml (si lo hace)     │
│                                                              │
│ core/crates/tui/                                            │
│ └── CONSUME: configs/services-catalog.toml (si lo hace)     │
│                                                              │
│ core/crates/syntaxis-api/                                   │
│ └── CONSUME: configs/services-catalog.toml (si lo hace)     │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│ PROJECT-PROVISIONING (Otro repositorio)                     │
│ ─────────────────────────────────────────────────────────── │
│                                                              │
│ /Users/Akasha/project-provisioning/                         │
│ provisioning/platform/provctl-bridge/                       │
│ └── src/catalog.rs                                          │
│     - ServiceCatalog struct (lee TOML)                      │
│     - 3 generadores de código (Docker, K8s, TF)             │
│     - Tests: 34/34 passing ✅                               │
│                                                              │
│ └── examples/catalog-cli.rs                                 │
│     - CLI tool que apunta a syntaxis TOML                   │
│     - const CATALOG_PATH = /Users/.../services-catalog.toml │
└─────────────────────────────────────────────────────────────┘

CONEXIÓN ACTUAL:
    catalog-cli.rs (provctl-bridge)
         ↓
    reads: /Users/Akasha/Development/syntaxis/configs/services-catalog.toml
         ↓
    ServiceCatalog::from_file()
         ↓
    Genera Docker/K8s/Terraform
         ↓
    Tests pasan ✅
```

---

## ✅ Lo Que SÍ Funciona Hoy

### 1. Archivo Central TOML (CONFIRMADO)

**Ubicación**: `/Users/Akasha/Development/syntaxis/configs/services-catalog.toml`

**Consumidores CONFIRMADOS**:
- ✅ `catalog-cli.rs` en provctl-bridge
- ✅ `scripts/provisioning/service-catalog.nu` (NuShell)
- ✅ `scripts/provisioning/test-catalog.nu` (NuShell)

**Consumidores en syntaxis core**: ❌ **NINGUNO ENCONTRADO**
- Búsqueda realizada: No hay referencias a "catalog" en `/core/crates`

**Contenido** (6 servicios):
- ✅ syntaxis-cli
- ✅ syntaxis-tui
- ✅ syntaxis-api
- ✅ syntaxis-dashboard
- ✅ surrealdb
- ✅ nats

**Estructura**: TOML con secciones claras
- `[service.xxx]` - Definición del servicio
- `[groups.xxx]` - Agrupaciones
- `[pattern.xxx]` - Patrones de deployment
- `[ports]` - Mapeo de puertos

### 2. Módulo Rust (provctl-bridge)

**Archivo**: `/Users/Akasha/project-provisioning/provisioning/platform/provctl-bridge/src/catalog.rs`

**Estructura**:
```rust
pub struct ServiceCatalog {
    version: CatalogVersion,
    service: HashMap<String, ServiceDefinition>,
    preset: Option<HashMap<String, PresetDefinition>>,
    group: Option<HashMap<String, GroupDefinition>>,
    // ... más campos
}

impl ServiceCatalog {
    pub fn from_file<P: AsRef<Path>>(path: P) -> Result<Self, ...> {
        let contents = fs::read_to_string(path)?;
        let catalog: ServiceCatalog = toml::from_str(&contents)?;
        Ok(catalog)
    }
}
```

**Métodos existentes**:
- `from_file()` - Carga TOML
- `get_service()` - Obtiene servicio
- `get_preset_services()` - Obtiene servicios de preset
- `service_names()` - Lista de servicios
- `export_preset_yaml()` - Exporta a YAML
- Generadores: Docker, Kubernetes, Terraform

### 3. CLI Tool (catalog-cli)

**Ubicación**: `/Users/Akasha/project-provisioning/provisioning/platform/provctl-bridge/examples/catalog-cli.rs`

**Comandos** (8 funcionando):
```
list              - Listar servicios
show <name>       - Detalles de servicio
validate          - Validar integridad
generate <fmt>    - Generar IaC (docker, kubernetes, terraform)
patterns          - Listar patrones
ports             - Mapeo de puertos
groups            - Grupos de servicios
help              - Ayuda
```

**Estado**: 34/34 tests pasando ✅

### 4. Generadores de Código

**Formatos soportados**:
- ✅ Docker Compose
- ✅ Kubernetes manifests
- ✅ Terraform HCL

**Estado**: Tests de generación pasan ✅

---

## ❌ Lo Que NO Funciona / No Existe

### 1. Integración en syntaxis

**Pregunta crítica**: ¿Consume syntaxis el TOML de `/Users/Akasha/Development/syntaxis/configs/services-catalog.toml`?

**Estado**: 🔍 **DESCONOCIDO** - Necesario investigar

Búsqueda hecha:
```bash
grep -r "services-catalog" /Users/Akasha/Development/syntaxis --include="*.rs"
```
**Resultado**: Buscaré esto

### 2. API REST

**Estado**: ❌ **NO EXISTE**

Propuesto en `KCL_REST_API_DESIGN.md`:
```rust
// Propuesto pero no implementado
let routes = Router::new()
    .route("/api/v1/services", get(list_services))
    .route("/api/v1/patterns", get(list_patterns))
    // etc
```

**Realidad**: No hay servidor HTTP exponiendo el catalog

### 3. KCL Definitions

**Estado**: ✅ **SÍ EXISTEN, PERO...**

**Ubicación**: `/Users/Akasha/project-provisioning/provisioning/kcl/services.k`

**IMPORTANTE**: Este KCL es para PROVISIONING PLATFORM (infraestructura), NO para syntaxis services
- Define: `ServiceRegistry` schema para plataforma
- Categorías: "orchestration", "auth", "dns", "git", "registry", "api", "ui", "monitoring"
- Tipos: "platform", "infrastructure", "utility"
- Deployments: binary, docker, docker-compose, kubernetes, remote

**NO ES para**:
- Servicios de syntaxis (CLI, TUI, API, Dashboard, etc)
- El catalog TOML en `/Users/Akasha/Development/syntaxis/configs/services-catalog.toml`

**Relación**:
```
KCL en provisioning (services.k)
  └─ Para infraestructura de provisioning

TOML en syntaxis (services-catalog.toml)
  └─ Para servicios de syntaxis

Son INDEPENDIENTES, NO se sincronizan
```

### 4. Sincronización KCL ↔ TOML

**Estado**: ❌ **NO EXISTE**

**Preguntas sin responder**:
- ¿Dónde vivía el catalog antes en provisioning?
- ¿Se duplica en KCL?
- ¿Se sincroniza?

---

## 🔴 Problemas Reales Identificados

### Problema 1: Recompilación para cambios

**Situación**:
```bash
# Para cambiar el catalog hoy:
1. Edit /Users/Akasha/Development/syntaxis/configs/services-catalog.toml
2. ¿syntaxis se da cuenta automáticamente? ← NO SABEMOS
3. ¿syntaxis recompila? ← PROBABLEMENTE
```

**Impacto**: Si cambias TOML, necesitas `cargo build` en syntaxis

### Problema 2: Consumidor desconocido

**Pregunta**: ¿Quién lee el TOML en syntaxis?

**Búsqueda necesaria**:
```bash
grep -r "services-catalog\|ServiceCatalog" /Users/Akasha/Development/syntaxis/core --include="*.rs"
```

### Problema 3: Múltiples fuentes de verdad (potencial)

**Posibilidades**:
```
Opción A: TOML en syntaxis ES la verdad
         └─ provisioning lo copia/referencia
         └─ KCL en provisioning NO existe

Opción B: KCL en provisioning ES la verdad
         └─ TOML en syntaxis se sincroniza
         └─ Posible desincronización

Opción C: Ambos existen independientemente
         └─ Riesgo alto de inconsistencia
```

### Problema 4: Solo Rust puede consumir

**Realidad**:
- syntaxis (Rust) ✅ puede usar TOML directamente
- Node.js app ❌ ¿cómo obtiene el catalog?
- Python script ❌ ¿cómo obtiene el catalog?
- DevOps ✅ puede parsear TOML (manual)

---

## 📋 Investigaciones Necesarias

### 1️⃣ Búsqueda: ¿Cómo consume syntaxis el catalog?

```bash
# En syntaxis
find . -name "*.rs" -type f | xargs grep -l "catalog\|service.*definition" | head -20
```

**Resultado esperado**: Archivos que cargan o usan el TOML

### 2️⃣ Búsqueda: ¿Existe algo en provisioning?

```bash
find /Users/Akasha/project-provisioning -name "*.k" -type f | head -10
```

**Resultado esperado**: Saber si hay KCL definitions

### 3️⃣ Búsqueda: ¿Dónde está el primer catalog?

```bash
# En project-provisioning
find . -name "*catalog*" -o -name "*service*definition*" | grep -v target
```

**Resultado esperado**: Dónde vivía el catalog originalmente

### 4️⃣ Lectura: ¿Qué hace el catalog-cli realmente?

```bash
# Ver qué comandos existen
cargo run --example catalog-cli -- list
cargo run --example catalog-cli -- show syntaxis-cli
```

**Resultado esperado**: Confirmar que está funcionando

---

## 🎯 Lo Que Debemos Entender

**Antes de cualquier arquitectura**:

1. **¿Dónde vive LA VERDAD hoy?**
   - ¿En `/Users/Akasha/Development/syntaxis/configs/services-catalog.toml`?
   - ¿O en provisioning?
   - ¿O en ambos (y cómo se sincronizan)?

2. **¿Quién la consume?**
   - syntaxis ← necesario confirmación
   - provisioning ← confirmado (catalog-cli)
   - Otros ← necesario identificar

3. **¿Cuál es el problema REAL?**
   - ¿Recompilación de syntaxis cuando cambia TOML?
   - ¿Inconsistencia entre TOML y KCL?
   - ¿Apps no-Rust sin acceso al catalog?
   - ¿Otro problema?

4. **¿Qué cambio MÍNIMO resolvería el problema?**
   - Extender catalog-cli para servir HTTP (REST API)?
   - Sincronizar TOML ↔ KCL?
   - Mover TOML a provisioning?
   - Crear bindings multi-lenguaje?

---

## 🚀 Próximos Pasos

### PASO 1: Investigar syntaxis
```bash
# Ver si syntaxis usa el catalog
grep -r "services-catalog\|ServiceCatalog\|catalog\|service.*definition" \
  /Users/Akasha/Development/syntaxis/core \
  --include="*.rs" \
  | head -30
```

### PASO 2: Investigar provisioning
```bash
# Ver si hay KCL definitions
find /Users/Akasha/project-provisioning \
  -name "*.k" \
  -type f \
  | head -20
```

### PASO 3: Ejecutar catalog-cli
```bash
cd /Users/Akasha/project-provisioning/provisioning/platform/provctl-bridge
cargo run --example catalog-cli -- list
cargo run --example catalog-cli -- validate
```

### PASO 4: Entender el flujo actual
```bash
# ¿Qué tests hay?
ls -la /Users/Akasha/project-provisioning/provisioning/platform/provctl-bridge/tests/
```

---

## 🔴 HALLAZGOS CRÍTICOS (Basado en Investigación Real)

### 1. El TOML Catalog NO es consumido por syntaxis core

**Hecho**: No hay referencias a "catalog" en `/Users/Akasha/Development/syntaxis/core/crates`

**Implicación**:
- El TOML existe pero NO controla el comportamiento de syntaxis
- syntaxis está diseñado INDEPENDIENTEMENTE del catalog
- El catalog es para PROVISIONING/DEPLOYMENT, no para el código de syntaxis

### 2. El Catalog ES consumido por provisioning tools

**Consumidores REALES**:
- ✅ `catalog-cli.rs` - CLI tool que lee y genera IaC
- ✅ `scripts/provisioning/service-catalog.nu` - Script NuShell
- ✅ `scripts/provisioning/test-catalog.nu` - Tests NuShell

**Propósito**: Conocer qué servicios están disponibles para generar IaC

### 3. KCL existe PERO es para otra cosa

**KCL en provisioning** (`/Users/Akasha/project-provisioning/provisioning/kcl/services.k`):
- ✅ Define schema para infraestructura de provisioning platform
- ❌ NO define servicios de syntaxis
- ❌ NO se sincroniza con TOML catalog

**Relación**:
```
provisioning/kcl/services.k  (infra de provisioning)
           ↕
           X (NO sincroniza)
           ↕
syntaxis/configs/services-catalog.toml (servicios de syntaxis)
```

### 4. El "Problema Real" que definimos NO existe

**Asunción Inicial**:
"¿Cambiar catalog requiere recompilación de syntaxis?"

**Realidad**:
- syntaxis NO lee el catalog TOML
- Cambiar el TOML NO afecta a syntaxis
- El catalog es para provisioning/deployment

---

## 📌 Conclusión Real

**Hoy tenemos**:
- ✅ Un TOML catalog en syntaxis (pero syntaxis NO lo usa)
- ✅ Tooling en provisioning que SÍ lo usa
- ✅ Generadores de IaC que funcionan
- ✅ Tests que pasan (34/34)
- ✅ Scripts NuShell para exploración

**El "problema" de ARCHITECTURE_REVISION.md NO EXISTE**:
- ✅ No hay acoplamiento Rust (sintaxis es independiente)
- ✅ No hay recompilación necesaria (no consume el catalog)
- ✅ No hay múltiples fuentes de verdad (el catalog es para provisioning)

**Lo que SÍ hay**:
- ✅ Dos sistemas SEPARADOS funcionando bien
  - syntaxis: código Rust independiente
  - provisioning: tools que entienden servicios

---

## ⚠️ Reevaluación Necesaria

Toda la arquitectura propuesta (KCL + REST API, etc) se basaba en problema que **NO existe**.

**Preguntas correctas ahora**:

1. ¿**Cuál es el problema REAL que queremos resolver?**
   - ¿Mejor documentation de servicios?
   - ¿API multi-lenguaje para descubrimiento?
   - ¿Sincronización entre entornos?
   - ¿Otra cosa?

2. ¿**El catalog TOML está cumpliendo su propósito?**
   - ¿Es usado por algo?
   - ¿Genera valor?
   - ¿Está sincronizado?

3. ¿**Hay que hacer algo o está bien como está?**
   - Provisioning tools funcionan ✅
   - Generación de IaC funciona ✅
   - Tests pasan ✅
   - ¿Qué está "roto"?

---

**PRÓXIMA ACCIÓN**: Entender cuál es el problema REAL que queremos resolver con este catalog.