@evolith/core-domain 1.0.0 → 1.0.1

package/rulesets/topologies/edge-computing/evolution.es.md

@@ -0,0 +1,257 @@
+# Guía de Evolución de Computación en el Borde
+
+> **Navegación Bilingüe:** [English](./evolution.md) | [Español](./evolution.es.md)
+
+**Propietario:** Ingeniería de Plataforma
+**Topología:** Computación en el Borde
+
+## Migración de la Nube al Borde
+
+Mover workloads de la nube centralizada al borde requiere planificación cuidadosa y migración incremental.
+
+### Fases de Migración
+
+```
+Fase 1: Evaluación
+  ├── Análisis de workloads
+  ├── Requisitos de latencia
+  └── Necesidades de residencia de datos
+
+Fase 2: Piloto
+  ├── Seleccionar workloads elegibles para el borde
+  ├── Desplegar en una sola región
+  └── Validar rendimiento
+
+Fase 3: Expansión
+  ├── Implementar en múltiples regiones
+  ├── Implementar estrategias de sincronización
+  └── Monitorear y optimizar
+
+Fase 4: Optimización
+  ├── Ajustar caché
+  ├── Optimizar inicios en frío
+  └── Optimización de costos
+```
+
+### Elegibilidad de Workloads
+
+```bash
+# Analizar workloads para elegibilidad en el borde
+edge-cli migration analyze \
+  --service user-api \
+  --check-latency \
+  --check-data-residency \
+  --check-dependencies
+
+# Salida:
+# SERVICE: user-api
+# EDGE_ELIGIBLE: yes
+# LATENCY_BENEFIT: 45ms improvement
+# DATA_RESIDENCY: compliant
+# DEPENDENCIES: all available at edge
+# RECOMMENDATION: migrate
+```
+
+### Lista de Verificación de Migración
+
+| Criterio | Requisito | Estado |
+|----------|-----------|--------|
+| Mejora de latencia | > 20ms beneficio | [PASS] |
+| Residencia de datos | Cumplimiento con reglas regionales | [PASS] |
+| Dependencia del origen | Mínima o cacheable | [PASS] |
+| Gestión de estado | Stateless o primero local | [PASS] |
+| Manejo de errores | Degradación elegante | [PASS] |
+
+## Evolución de Estrategias de Sincronización
+
+A medida que los despliegues del borde maduran, las estrategias de sincronización evolucionan de simples a sofisticadas.
+
+### Ruta de Evolución
+
+```
+Etapa 1: Solo Solicitud
+  ├── Contenido obtenido bajo demanda
+  ├── Implementación simple
+  └── Alta latencia en fallo
+
+Etapa 2: Basada en Envío
+  ├── Origen envía actualizaciones
+  ├── Menor latencia
+  └── Mayor uso de ancho de banda
+
+Etapa 3: Híbrida
+  ├── Envío para contenido crítico
+  ├── Solicitud para contenido dinámico
+  └── Enfoque equilibrado
+
+Etapa 4: Inteligente
+  ├── Prefetching basado en ML
+  ├── Sincronización predictiva
+  └── Estrategias adaptativas
+```
+
+### Selección de Estrategia de Sincronización
+
+```yaml
+sync_evolution:
+  stage_1:
+    name: "pull-only"
+    description: "Obtención simple bajo demanda"
+    use_case: "despliegue inicial, bajo tráfico"
+    complexity: "baja"
+    
+  stage_2:
+    name: "push-based"
+    description: "Actualizaciones iniciadas por el origen"
+    use_case: "contenido estático, patrones predecibles"
+    complexity: "media"
+    
+  stage_3:
+    name: "hybrid"
+    description: "Estrategias mixtas de envío/solicitud"
+    use_case: "cargas de trabajo mixtas, necesidades equilibradas"
+    complexity: "alta"
+    
+  stage_4:
+    name: "intelligent"
+    description: "Optimización de sincronización basada en ML"
+    use_case: "despliegues maduros, alto tráfico"
+    complexity: "muy alta"
+```
+
+## Matriz de Decisión Borde vs Nube
+
+Elegir entre ejecución en el borde y la nube depende de múltiples factores.
+
+### Factores de Decisión
+
+| Factor | Favorece el Borde | Favorece la Nube |
+|--------|-------------------|------------------|
+| Requisito de latencia | < 50ms | > 100ms |
+| Localidad de datos | Específico del usuario | Global |
+| Complejidad de cómputo | Simple, stateless | Complejo, con estado |
+| Modelo de costo | Alto volumen de solicitudes | Cómputo burst |
+| Regulatorio | Residencia de datos | Ninguno |
+| Disponibilidad | Sin conexión necesario | En línea suficiente |
+
+### Flujo de Decisión
+
+```bash
+# Evaluar borde vs nube para un workload
+edge-cli decision evaluate \
+  --workload product-catalog \
+  --latency-budget 200ms \
+  --data-residency required \
+  --compute-complexity low
+
+# Salida:
+# WORKLOAD: product-catalog
+# EDGE_SCORE: 85/100
+# CLOUD_SCORE: 45/100
+# RECOMMENDATION: edge
+# REASONS:
+#   - Requisito de latencia cumplido en el borde
+#   - Cumplimiento de residencia de datos
+#   - Baja complejidad de cómputo
+```
+
+## Arquitectura Neutral al Proveedor (Ref: ADR-0096)
+
+La arquitectura del borde debe permanecer neutral al proveedor para evitar el bloqueo de proveedor.
+
+### Capas de Abstracción
+
+```
+┌─────────────────────────────────────────────────┐
+│  Capa de Aplicación                             │
+│  ┌─────────────────────────────────────────┐   │
+│  │  API del Borde                          │   │
+│  │  - Ejecución de funciones               │   │
+│  │  - Operaciones de almacenamiento        │   │
+│  │  - Utilidades de redes                  │   │
+│  └─────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────┘
+                         │
+┌─────────────────────────────────────────────────┐
+│  Capa de Abstracción del Proveedor             │
+│  ┌─────────────────────────────────────────┐   │
+│  │  Interfaz del Proveedor del Borde       │   │
+│  │  - Cloudflare Workers                   │   │
+│  │  - AWS Lambda@Edge                      │   │
+│  │  - Azure Functions Premium              │   │
+│  │  - Fastly Compute@Edge                  │   │
+│  └─────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────┘
+```
+
+### Interfaz del Proveedor
+
+```typescript
+interface EdgeProvider {
+  // Ejecución de funciones
+  executeFunction(
+    name: string,
+    request: EdgeRequest
+  ): Promise<EdgeResponse>;
+  
+  // Operaciones de almacenamiento
+  getStorage(key: string): Promise<ArrayBuffer>;
+  setStorage(key: string, value: ArrayBuffer): Promise<void>;
+  
+  // Redes
+  fetch(url: string, init?: RequestInit): Promise<Response>;
+  
+  // Específico de la plataforma
+  getRegion(): string;
+  getNode(): string;
+}
+```
+
+### Despliegue Multi-Proveedor
+
+```yaml
+providers:
+  primary:
+    name: cloudflare
+    region: us-east-1
+    functions: true
+    storage: true
+    
+  secondary:
+    name: aws
+    region: us-west-2
+    functions: true
+    storage: true
+    
+  fallback:
+    name: azure
+    region: westeurope
+    functions: true
+    storage: false
+```
+
+## Hoja de Ruta de Evolución Tecnológica
+
+### Corto Plazo (0-6 meses)
+
+- [ ] Desplegar funciones básicas del borde
+- [ ] Implementar datos primero local
+- [ ] Configurar monitoreo y alertas
+- [ ] Establecer estrategias de sincronización
+
+### Mediano Plazo (6-12 meses)
+
+- [ ] Resolución de conflictos avanzada
+- [ ] Prefetching basado en ML
+- [ ] Replicación multi-región
+- [ ] Optimización de costos
+
+### Largo Plazo (12+ meses)
+
+- [ ] Bases de datos nativas del borde
+- [ ] Cómputo distribuido en el borde
+- [ ] Aprendizaje federado
+- [ ] Operaciones autónomas del borde
+
+---
+[Volver al Perfil de Computación en el Borde](./README.es.md)

package/rulesets/topologies/edge-computing/evolution.md

@@ -0,0 +1,257 @@
+# Edge Computing — Evolution Guide
+
+> **Bilingual Navigation:** [English](./evolution.md) | [Español](./evolution.es.md)
+
+**Owner:** Platform Engineering
+**Topology:** Edge Computing
+
+## Cloud to Edge Migration
+
+Moving workloads from centralized cloud to edge requires careful planning and incremental migration.
+
+### Migration Phases
+
+```
+Phase 1: Assessment
+  ├── Workload analysis
+  ├── Latency requirements
+  └── Data residency needs
+
+Phase 2: Pilot
+  ├── Select edge-eligible workloads
+  ├── Deploy to single region
+  └── Validate performance
+
+Phase 3: Expansion
+  ├── Roll out to multiple regions
+  ├── Implement sync strategies
+  └── Monitor and optimize
+
+Phase 4: Optimization
+  ├── Fine-tune caching
+  ├── Optimize cold starts
+  └── Cost optimization
+```
+
+### Workload Eligibility
+
+```bash
+# Analyze workloads for edge eligibility
+edge-cli migration analyze \
+  --service user-api \
+  --check-latency \
+  --check-data-residency \
+  --check-dependencies
+
+# Output:
+# SERVICE: user-api
+# EDGE_ELIGIBLE: yes
+# LATENCY_BENEFIT: 45ms improvement
+# DATA_RESIDENCY: compliant
+# DEPENDENCIES: all available at edge
+# RECOMMENDATION: migrate
+```
+
+### Migration Checklist
+
+| Criteria | Requirement | Status |
+|----------|-------------|--------|
+| Latency improvement | > 20ms benefit | [PASS] |
+| Data residency | Compliant with region rules | [PASS] |
+| Origin dependency | Minimal or cacheable | [PASS] |
+| State management | Stateless or local-first | [PASS] |
+| Error handling | Graceful degradation | [PASS] |
+
+## Sync Strategy Evolution
+
+As edge deployments mature, sync strategies evolve from simple to sophisticated.
+
+### Evolution Path
+
+```
+Stage 1: Pull-Only
+  ├── Content fetched on demand
+  ├── Simple implementation
+  └── High latency on miss
+
+Stage 2: Push-Based
+  ├── Origin pushes updates
+  ├── Lower latency
+  └── Higher bandwidth usage
+
+Stage 3: Hybrid
+  ├── Push for critical content
+  ├── Pull for dynamic content
+  └── Balanced approach
+
+Stage 4: Intelligent
+  ├── ML-based prefetching
+  ├── Predictive sync
+  └── Adaptive strategies
+```
+
+### Sync Strategy Selection
+
+```yaml
+sync_evolution:
+  stage_1:
+    name: "pull-only"
+    description: "Simple on-demand fetching"
+    use_case: "initial deployment, low traffic"
+    complexity: "low"
+    
+  stage_2:
+    name: "push-based"
+    description: "Origin-initiated updates"
+    use_case: "static content, predictable patterns"
+    complexity: "medium"
+    
+  stage_3:
+    name: "hybrid"
+    description: "Mixed push/pull strategies"
+    use_case: "mixed workloads, balanced needs"
+    complexity: "high"
+    
+  stage_4:
+    name: "intelligent"
+    description: "ML-driven sync optimization"
+    use_case: "mature deployments, high traffic"
+    complexity: "very high"
+```
+
+## Edge vs Cloud Decision Matrix
+
+Choosing between edge and cloud execution depends on multiple factors.
+
+### Decision Factors
+
+| Factor | Edge Favors | Cloud Favors |
+|--------|-------------|--------------|
+| Latency requirement | < 50ms | > 100ms |
+| Data locality | User-specific | Global |
+| Compute complexity | Simple, stateless | Complex, stateful |
+| Cost model | High request volume | Burst compute |
+| Regulatory | Data residency | None |
+| Availability | Offline needed | Online sufficient |
+
+### Decision Flow
+
+```bash
+# Evaluate edge vs cloud for a workload
+edge-cli decision evaluate \
+  --workload product-catalog \
+  --latency-budget 200ms \
+  --data-residency required \
+  --compute-complexity low
+
+# Output:
+# WORKLOAD: product-catalog
+# EDGE_SCORE: 85/100
+# CLOUD_SCORE: 45/100
+# RECOMMENDATION: edge
+# REASONS:
+#   - Latency requirement met at edge
+#   - Data residency compliance
+#   - Low compute complexity
+```
+
+## Provider-Neutral Architecture (Ref: ADR-0096)
+
+The edge architecture must remain provider-neutral to avoid vendor lock-in.
+
+### Abstraction Layers
+
+```
+┌─────────────────────────────────────────────────┐
+│  Application Layer                              │
+│  ┌─────────────────────────────────────────┐   │
+│  │  Edge API                                │   │
+│  │  - Function execution                    │   │
+│  │  - Storage operations                    │   │
+│  │  - Networking utilities                  │   │
+│  └─────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────┘
+                         │
+┌─────────────────────────────────────────────────┐
+│  Provider Abstraction Layer                     │
+│  ┌─────────────────────────────────────────┐   │
+│  │  Edge Provider Interface                 │   │
+│  │  - Cloudflare Workers                    │   │
+│  │  - AWS Lambda@Edge                       │   │
+│  │  - Azure Functions Premium               │   │
+│  │  - Fastly Compute@Edge                   │   │
+│  └─────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────┘
+```
+
+### Provider Interface
+
+```typescript
+interface EdgeProvider {
+  // Function execution
+  executeFunction(
+    name: string,
+    request: EdgeRequest
+  ): Promise<EdgeResponse>;
+  
+  // Storage operations
+  getStorage(key: string): Promise<ArrayBuffer>;
+  setStorage(key: string, value: ArrayBuffer): Promise<void>;
+  
+  // Networking
+  fetch(url: string, init?: RequestInit): Promise<Response>;
+  
+  // Platform-specific
+  getRegion(): string;
+  getNode(): string;
+}
+```
+
+### Multi-Provider Deployment
+
+```yaml
+providers:
+  primary:
+    name: cloudflare
+    region: us-east-1
+    functions: true
+    storage: true
+    
+  secondary:
+    name: aws
+    region: us-west-2
+    functions: true
+    storage: true
+    
+  fallback:
+    name: azure
+    region: westeurope
+    functions: true
+    storage: false
+```
+
+## Technology Evolution Roadmap
+
+### Short-Term (0-6 months)
+
+- [ ] Deploy basic edge functions
+- [ ] Implement local-first data
+- [ ] Set up monitoring and alerting
+- [ ] Establish sync strategies
+
+### Medium-Term (6-12 months)
+
+- [ ] Advanced conflict resolution
+- [ ] ML-based prefetching
+- [ ] Multi-region replication
+- [ ] Cost optimization
+
+### Long-Term (12+ months)
+
+- [ ] Edge-native databases
+- [ ] Distributed computing at edge
+- [ ] Federated learning
+- [ ] Autonomous edge operations
+
+---
+[Back to Edge Computing Profile](./README.md)

package/rulesets/topologies/edge-computing/fixtures/invalid.topology.config.json

@@ -0,0 +1,6 @@
+{
+  "topology": "edge-computing",
+  "syncStrategy": "invalid-strategy",
+  "edgeIsolation": false,
+  "conflictResolution": ""
+}

package/rulesets/topologies/edge-computing/fixtures/valid.topology.config.json

@@ -0,0 +1,6 @@
+{
+  "topology": "edge-computing",
+  "syncStrategy": "offline-first",
+  "edgeIsolation": true,
+  "conflictResolution": "last-write-wins"
+}

package/rulesets/topologies/edge-computing/maturity.es.md

@@ -0,0 +1,36 @@
+# Guia de Adopcion, Operacion y Evolucion de Edge Computing
+
+> **Navegacion Bilingue:** [English Version](./maturity.md)
+
+## Adoption
+
+Adopte esta topologia cuando latencia, localidad, tolerancia offline, ubicacion regulatoria o procesamiento cercano a dispositivos requiera ejecucion fuera del runtime central. Comience con justificacion de localidad documentada, estrategia de sincronizacion explicita y aislamiento de nodo edge.
+
+## Operations
+
+Opere nodos edge con observabilidad store-and-forward, sincronizacion consciente de conflictos y tolerancia a conectividad intermitente. Monitoree lag de sincronizacion, tasas de conflicto y duracion offline como parte de la validacion normal de arquitectura.
+
+## Security
+
+Implemente autenticacion y autorizacion en cada nodo edge. Use secretos inyectados por entorno con capacidad de rotacion apropiados para entornos restringidos. Nunca incruste credenciales en artefactos de despliegue edge.
+
+## Resilience
+
+Disene nodos edge para operacion autonoma durante particiones de red con patrones de persistencia offline-first. Prefiera sincronizacion en background con resolucion explicita de conflictos sobre acoplamiento en tiempo real.
+
+## Patterns and Anti-Patterns
+
+Use bases de datos locales offline-first con sincronizacion en background, estrategias explicitas de resolucion de conflictos (last-write-wins, merge, manual) y observabilidad store-and-forward. No bifurque logica de dominio en el edge, asuma conectividad permanente ni omita gobernanza central por conveniencia edge.
+
+## Evolution
+
+Migre a edge computing solo cuando latencia, localidad o restricciones regulatorias justifiquen la complejidad operativa. Preserve las fronteras de ownership de dominio y los contratos de sincronizacion para que la reubicacion de workloads siga siendo deliberada.
+
+## Validation Checklist
+
+- Valide la configuracion de topologia con `topology.config.schema.json` y ambos fixtures.
+- Ejecute la evaluacion Native y OPA mediante el plano de control compartido.
+- Confirme ADRs aprobados, guia bilingue y pruebas positivas y negativas reproducibles.
+
+---
+[Volver al Perfil Edge Computing](./README.es.md)

package/rulesets/topologies/edge-computing/maturity.md

@@ -0,0 +1,36 @@
+# Edge Computing Adoption, Operations, and Evolution Guide
+
+> **Bilingual Navigation:** [Version en Espanol](./maturity.es.md)
+
+## Adoption
+
+Adopt this topology when latency, locality, offline tolerance, regulatory placement, or device-adjacent processing requires execution outside the central runtime. Start with documented locality justification, explicit synchronization strategy, and edge node isolation.
+
+## Operations
+
+Operate edge nodes with store-and-forward observability, conflict-aware synchronization, and intermittent connectivity tolerance. Monitor sync lag, conflict rates, and offline duration as part of normal architecture validation.
+
+## Security
+
+Enforce authentication and authorization at each edge node. Use environment-injected secrets with rotation capability appropriate to constrained environments. Never embed credentials in edge deployment artifacts.
+
+## Resilience
+
+Design edge nodes for autonomous operation during network partitions with offline-first persistence patterns. Prefer background synchronization with explicit conflict resolution over real-time coupling.
+
+## Patterns and Anti-Patterns
+
+Use offline-first local databases with background sync, explicit conflict resolution strategies (last-write-wins, merge, manual), and store-and-forward observability. Do not fork domain logic at the edge, assume always-on connectivity, or bypass central governance for edge convenience.
+
+## Evolution
+
+Move to edge computing only when latency, locality, or regulatory constraints justify the operational complexity. Preserve domain ownership boundaries and synchronization contracts so that workload relocation remains deliberate.
+
+## Validation Checklist
+
+- Validate the topology configuration against `topology.config.schema.json` and both fixtures.
+- Run Native and OPA policy evaluation through the shared control plane.
+- Confirm approved ADRs, bilingual guidance, and reproducible positive and negative tests.
+
+---
+[Back to Edge Computing Profile](./README.md)

package/rulesets/topologies/edge-computing/mcp/mcp-manifest.json

@@ -0,0 +1,72 @@
+{
+  "protocolVersion": "2025-03-26",
+  "topologyId": "edge-computing",
+  "description": "MCP interface for the Edge Computing topology. Provides tools for inspecting and validating edge deployment configurations, resources for manifest and ruleset access, and prompts for edge-governed implementation and extraction-readiness guidance.",
+  "capabilities": {
+    "tools": {},
+    "resources": {},
+    "prompts": {}
+  },
+  "tools": [
+    {
+      "name": "evolith-topology-inspect",
+      "description": "Inspect an Edge Computing topology configuration and return its parsed manifest, deployment targets, and corpus artifact references.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "configPath": {
+            "type": "string",
+            "description": "Path to the Edge Computing configuration file"
+          },
+          "includeTargets": {
+            "type": "boolean",
+            "description": "Include edge deployment target metadata"
+          }
+        },
+        "required": ["configPath"]
+      }
+    },
+    {
+      "name": "evolith-topology-validate",
+      "description": "Validate an Edge Computing configuration against the topology ruleset and OPA policies, returning pass/fail per gate.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "configPath": {
+            "type": "string",
+            "description": "Path to the Edge Computing configuration to validate"
+          },
+          "strictMode": {
+            "type": "boolean",
+            "description": "Fail on warnings, not just errors"
+          }
+        },
+        "required": ["configPath"]
+      }
+    }
+  ],
+  "resources": [
+    {
+      "uri": "evolith://topologies/edge-computing/manifest",
+      "name": "Edge Computing Topology Manifest",
+      "description": "Full topology manifest for Edge Computing, including metadata, artifact references, and corpus configuration.",
+      "mimeType": "application/json"
+    },
+    {
+      "uri": "evolith://topologies/edge-computing/rulesets",
+      "name": "Edge Computing Rulesets",
+      "description": "All ruleset files for Edge Computing: native rules JSON, OPA Rego policies, and WASM bundle.",
+      "mimeType": "application/json"
+    }
+  ],
+  "prompts": [
+    {
+      "name": "topology-aware-implementation",
+      "description": "Guides AI-assisted implementation to respect Edge Computing topology constraints, offline resilience, and resource limits."
+    },
+    {
+      "name": "extraction-readiness-review",
+      "description": "Evaluates whether a modular monolith module is ready for extraction into a distributed edge deployment, checking coupling, ownership, and contract boundaries."
+    }
+  ]
+}