syntaxis/docs/provision/problem-statement-correct.md

# 🎯 PLANTEAMIENTO DEL PROBLEMA - VERSIÓN CORRECTA

**Fecha**: 2025-11-20
**Estado**: Análisis crítico basado en retroalimentación real
**Autor**: Corrección necesaria

---

## ❌ Lo Que Estaba Mal

### Asunción 1: El Catalog TOML era fuente de verdad
**Problema**: TOML es ingestionable, no eficiente, requiere compilación continua

### Asunción 2: Tenemos "dos sistemas desconectados"
**Problema**: Es incorrecto - YA EXISTE un bridge entre project-provisioning y provctl

### Asunción 3: El catalog TOML debería ser el puente
**Problema**: El TOML no es el formato adecuado, ya hay un bridge mejor

---

## ✅ El Problema REAL (Corregido)

### El Contexto Real

```
project-provisioning
  └─ Orquesta infraestructura (máquinas, redes, servicios)
  └─ Usa KCL para definiciones
  └─ Tiene bridge para conectar con provctl

provctl
  └─ Controla servicios locales y remotos
  └─ Sabe cómo ejecutar, monitorear, orchestrar servicios
  └─ Lee configuración

syntaxis
  └─ Es UN PROYECTO como cualquier otro
  └─ Podría ser un "taskservs" (task service) en provisioning
  └─ Debería poder:
     ├─ Definir sus funcionalidades
     ├─ Declarar sus requisitos de infra
     ├─ Describir cómo se gestiona (systemctl, provctl, etc)
     └─ Generar catálogo automáticamente
```

### El Problema REAL

**HOY**:
```
syntaxis developer define proyecto en Rust
  ↓
¿Cómo describe qué servicios necesita?
¿Cómo describe cómo se ejecutan?
¿Cómo se integra con provisioning y provctl?
  ↓
PROBLEMA: No hay un mecanismo DECLARATIVO para esto
```

**Solución necesaria**:
```
syntaxis project
  ↓
Archivo declarativo (NO TOML): project.yaml o similar
  └─ Define: servicios, requisitos, modos de ejecución
  └─ Generado/mantenido: por desarrollador
  └─ Consumido por: provisioning, provctl, installer
  ↓
provisioning lo ve como taskservs
  ├─ Sabe: qué services necesita syntaxis
  ├─ Sabe: requisitos de infra
  └─ Puede: orchestrar como parte del sistema

provctl lo ve como:
  ├─ Sabe: cómo ejecutar cada servicio
  ├─ Sabe: health checks, dependencias
  └─ Puede: gestionar ciclo de vida

syntaxis installer lo usa para:
  ├─ Ofrecer presets (local, dev, prod)
  ├─ Integrar con provisioning si disponible
  └─ Integrar con provctl si disponible
```

---

## 📋 El Flujo Correcto

### 1. Developer declara su proyecto

**Archivo**: `syntaxis.declarative.k` o `syntaxis.yaml`

```yaml
# DECLARACIÓN DE PROYECTO (no TOML compilado)
# Developer lo mantiene, es legible, NO requiere compilación continua

project: syntaxis
version: 1.0.0
description: "Project management platform"

services:
  cli:
    name: syntaxis-cli
    type: binary
    # ... metadatos

  api:
    name: syntaxis-api
    type: service
    port: 3000
    requires: [database, cache]
    # ... metadatos

  database:
    name: surrealdb
    type: database
    # ... metadatos

deployment_modes:
  local:
    description: "Single machine, development"
    services: [cli]
    manager: manual  # Developer runs manually

  dev:
    description: "Full dev stack"
    services: [cli, api, database, cache]
    manager: provctl  # provctl manages these

  production:
    description: "HA production"
    services: [cli, api, database, cache, nats]
    manager: provisioning  # Full provisioning manages
```

### 2. provisioning lo consume

**Cómo**:
```
provisioning/kcl/syntaxis-taskservs.k

service_syntaxis = ServiceRegistry {
    name: "syntaxis"
    # Importa/consume: syntaxis.declarative.k
    services: import_from("syntaxis.declarative.k").services
    deployment_mode: "production"
}
```

**Beneficio**:
- syntaxis es ahora un "taskservs" en provisioning
- Provisioning conoce sus requisitos
- Se puede orchestrar con otros servicios

### 3. provctl lo consume

**Cómo**:
```
provctl config --from-project /path/to/syntaxis

Busca: syntaxis.declarative.k
Lee: deployment_modes.production (o lo que pidas)
Genera: configuración local para provctl
Ejecuta: servicios según deployment_mode.manager = "provctl"
```

**Beneficio**:
- provctl sabe cómo ejecutar servicios de syntaxis
- Puede monitorear health
- Puede orchestrar en múltiples máquinas

### 4. syntaxis installer lo consume

**Cómo**:
```
syntaxis-installer

Lee: syntaxis.declarative.k
Ofrece presets:
  - local: "Instala solo CLI"
  - dev: "Instala todo para desarrollo"
  - production: "Usa provisioning para HA"

Si desarrollo elige "dev":
  ├─ Detecta provctl disponible?
  │  ├─ SÍ: "provctl config --from-project . && provctl apply"
  │  └─ NO: "Sigue esta guía manual..."
  └─ Inicia servicios necesarios
```

---

## 🔄 Por Qué NO TOML

### Problemas del TOML compilado

```
❌ "Ingestionable"
   - Tenemos 436 líneas en services-catalog.toml
   - Requiere parsing manual en Rust
   - Cada cambio = recompilación (incómodo)

❌ No es "semántico"
   - TOML es data format, no schema
   - Sin validación nativa
   - Sin herencia/composición

❌ No es "legible para developer"
   - Developer ve: archivo generado/procesado
   - No ve: intención original
   - Difícil de mantener
```

### Ventajas de format declarativo (KCL o YAML)

```
✅ "Semántico"
   - Define SCHEMA, TIPOS, RESTRICCIONES
   - Valida automáticamente
   - Permite herencia

✅ "Legible"
   - Developer escribe UNA VEZ
   - Es su "fuente de verdad personal"
   - Fácil de mantener

✅ "Eficiente"
   - NO requiere compilación continua
   - Puede convertirse a múltiples formatos
   - Integrable con provisioning (KCL)
```

---

## 🎯 La Solución en 3 Partes

### Parte 1: Developer declara (NUEVA)

```
syntaxis/
├── Cargo.toml
├── CLAUDE.md
├── docs/
│   └── provision/
├── configs/
│   ├── database.toml (configuración, no catalog)
│   └── syntaxis.declarative.k  ← NUEVA
│       (Define: servicios, requisitos, modos)
└── src/
    └── main.rs
```

**syntaxis.declarative.k contiene**:
- Definición de servicios de syntaxis
- Requisitos (BD, cache, etc)
- Modos de deployment (local, dev, prod)
- Health checks, puertos, etc
- NO compilado, NO derivado

### Parte 2: provisioning lo importa (MEJORA)

```
provisioning/kcl/syntaxis-taskservs.k

# Importa declaración de syntaxis
syntaxis_def = import("/path/to/syntaxis/configs/syntaxis.declarative.k")

# Define cómo se provisiona
service_syntaxis = ServiceRegistry {
    name: "syntaxis"
    services: syntaxis_def.services
    deployment_mode: syntaxis_def.deployment_modes.production
    // ... específicos de provisioning
}
```

**Beneficio**: provisioning ve syntaxis como un "proyecto externo" que declare sus necesidades

### Parte 3: provctl lo consumes (NUEVA)

```
provctl config --from-declarative /path/to/syntaxis/configs/syntaxis.declarative.k --mode dev

├─ Lee: syntaxis.declarative.k
├─ Busca: deployment_modes.dev
├─ Genera: configuración para provctl
├─ Valida: health checks
└─ Resultado: listo para "provctl apply"
```

**Beneficio**: Developer puede usar provctl localmente sin provisioning

---

## 📊 Comparación: TOML vs Solución Correcta

| Aspecto | TOML Compilado | Solución Correcta |
|---------|---|---|
| **Ubicación** | syntaxis/configs/services-catalog.toml | syntaxis/configs/syntaxis.declarative.k |
| **Quién mantiene** | Tooling automático (catalog.rs) | Developer (una sola vez) |
| **Cambios requieren** | Recompilación | Solo guardar archivo |
| **Consumible por** | provisioning tools | provisioning, provctl, installer |
| **Validación** | Manual en Rust | Nativa en formato (KCL/YAML schema) |
| **Escalabilidad** | Crece exponencialmente | Modular, reutilizable |
| **Sincronización** | ¿Quién es source of truth? | El archivo del developer |

---

## 🚀 Implementación

### Fase 1: Definir formato declarativo

**Decisión**: ¿KCL o YAML?
- KCL: Type-safe, schema, validación nativa
- YAML: Más simple, menos overhead

**Recomendación**: KCL (aprovecha inversión en provisioning)

**Archivo**: `syntaxis.declarative.k`

```kcl
project:
    name = "syntaxis"
    version = "1.0.0"

service "api-server":
    type = "http_service"
    port = 3000
    image = "syntaxis:api-latest"

service "database":
    type = "database"
    port = 5432

deployment "local":
    description = "Single machine, development"
    services = ["api-server"]
    manager = "manual"
```

### Fase 2: Extender provisioning

Para que lea `syntaxis.declarative.k` como taskservs importable

### Fase 3: Extender provctl

Para que lea `syntaxis.declarative.k` y genere configuración local

### Fase 4: Extender syntaxis installer

Para que consuma `syntaxis.declarative.k` y ofrezca presets

---

## 📌 Conclusión

**El problema REAL**:
> syntaxis (como proyecto) NO tiene forma declarativa de describir sus servicios, requisitos, y modos de deployment. El TOML compilado es incómodo porque requiere recompilación continua y es "derivado", no "fuente de verdad".

**La solución REAL**:
> Crear un archivo declarativo (syntaxis.declarative.k) que:
> 1. Developer mantiene (una sola vez)
> 2. provisioning importa (como taskservs)
> 3. provctl consume (para gestión local)
> 4. installer usa (para presets)

**Por qué esto es mejor**:
- ✅ Developer es "dueño" de la declaración
- ✅ No requiere recompilación continua
- ✅ Es consumible por múltiples sistemas
- ✅ Escalable a otros proyectos
- ✅ Eficiente (legible, no ingestionable)