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

# 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

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)