@evolith/core-domain 1.0.0 → 1.0.1

package/rulesets/topologies/edge-computing/openapi/openapi.yaml

@@ -0,0 +1,187 @@
+openapi: "3.1.0"
+info:
+  title: "Edge Computing Topology — Core API Surface"
+  version: "0.1.0"
+  description: >
+    REST API surface specific to the Edge Computing topology.
+    Describes endpoints exposed by the Core API for querying,
+    inspecting, and validating Edge Computing topology instances.
+servers:
+  - url: "https://api.evolith.dev/v1"
+    description: "Evolith Core API (production)"
+paths:
+  /topologies/{id}:
+    get:
+      tags: [Topologies]
+      summary: "Retrieve Edge Computing topology information"
+      description: >
+        Returns the full topology record for Edge Computing, including
+        dimension, status, version, governance metadata, and corpus
+        artifact references (rulesets, OPA policies, ADRs, guidance).
+      operationId: "getEdgeComputingTopology"
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+            pattern: "^edge-computing$"
+            example: "edge-computing"
+      responses:
+        "200":
+          description: "Successful response with Edge Computing topology data"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/EnvelopeTopology"
+        "404":
+          description: "Topology not found"
+  /topologies/{id}/manifest:
+    get:
+      tags: [Topologies]
+      summary: "Get Edge Computing topology manifest"
+      description: >
+        Returns the full topology manifest for Edge Computing, with
+        artifact references, corpus configuration, and business
+        boundary declaration.
+      operationId: "getEdgeComputingManifest"
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+            pattern: "^edge-computing$"
+      responses:
+        "200":
+          description: "Successful response with Edge Computing manifest"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/EnvelopeManifest"
+  /topologies/{id}/validate:
+    post:
+      tags: [Topologies]
+      summary: "Validate Edge Computing topology rules"
+      description: >
+        Executes all applicable rulesets and OPA policies for Edge
+        Computing against a submitted configuration, returning pass/fail
+        per gate.
+      operationId: "validateEdgeComputingTopology"
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+            pattern: "^edge-computing$"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/ValidationRequest"
+      responses:
+        "200":
+          description: "Validation results"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/EnvelopeValidation"
+components:
+  schemas:
+    Envelope:
+      type: object
+      properties:
+        success:
+          type: boolean
+        data: {}
+        meta:
+          type: object
+          properties:
+            context:
+              type: string
+            timing:
+              type: number
+            schemaVersion:
+              type: string
+              pattern: "^\\d+\\.\\d+\\.\\d+$"
+          required: [context, timing, schemaVersion]
+      required: [success, data, meta]
+    EnvelopeTopology:
+      allOf:
+        - $ref: "#/components/schemas/Envelope"
+        - type: object
+          properties:
+            data:
+              $ref: "#/components/schemas/TopologyRecord"
+    EnvelopeManifest:
+      allOf:
+        - $ref: "#/components/schemas/Envelope"
+        - type: object
+          properties:
+            data:
+              $ref: "#/components/schemas/TopologyManifest"
+    EnvelopeValidation:
+      allOf:
+        - $ref: "#/components/schemas/Envelope"
+        - type: object
+          properties:
+            data:
+              $ref: "#/components/schemas/ValidationResult"
+    TopologyRecord:
+      type: object
+      properties:
+        id:
+          type: string
+          example: "edge-computing"
+        name:
+          type: string
+          example: "Edge Computing"
+        dimension:
+          type: string
+          example: "execution"
+        status:
+          type: string
+          enum: [accepted, draft, deprecated]
+        version:
+          type: string
+          example: "0.1.0"
+    TopologyManifest:
+      type: object
+      properties:
+        apiVersion:
+          type: string
+          example: "evolith.dev/topology/v1"
+        kind:
+          type: string
+          example: "TopologyManifest"
+        metadata:
+          type: object
+        spec:
+          type: object
+    ValidationRequest:
+      type: object
+      properties:
+        config:
+          type: object
+          description: "Configuration to validate against topology rules"
+      required: [config]
+    ValidationResult:
+      type: object
+      properties:
+        passed:
+          type: boolean
+        gates:
+          type: array
+          items:
+            type: object
+            properties:
+              gate:
+                type: string
+              passed:
+                type: boolean
+              evidence:
+                type: array
+                items:
+                  type: string

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

@@ -0,0 +1,148 @@
+# Guía de Operaciones de Computación en el Borde
+
+> **Navegación Bilingüe:** [English](./operations.md) | [Español](./operations.es.md)
+
+**Propietario:** Ingeniería de Plataforma
+**Topología:** Computación en el Borde
+
+## Gestión del Ciclo de Vida de Nodos
+
+Los nodos del borde siguen un ciclo de vida definido: aprovisionamiento, registro, activación, monitoreo, mantenimiento y baja.
+
+### Aprovisionamiento
+
+```bash
+# Registrar un nuevo nodo del borde
+edge-cli node register \
+  --node-id edge-node-01 \
+  --region us-west-2 \
+  --zone us-west-2a \
+  --role compute \
+  --capacity "cpu=4,memory=8Gi,storage=50Gi"
+```
+
+### Monitoreo de Salud
+
+Cada nodo reporta métricas de salud cada 15 segundos:
+
+| Métrica | Umbral | Acción al Exceder |
+|---------|--------|-------------------|
+| Latencia al origen | > 200ms | Activar conmutación por error |
+| Utilización de CPU | > 85% | Reducir cargas no críticas |
+| Uso de memoria | > 90% | Expulsar caché de menor uso |
+| Uso de disco | > 80% | Purgar contenido obsoleto |
+| Retraso de sincronización | > 30s | Escalar a operaciones |
+
+## Monitoreo de Sincronización de Contenido (Ref: EC-R01)
+
+La estrategia de sincronización garantiza la consistencia del contenido en toda la flota del borde.
+
+### Panel de Salud de Sincronización
+
+```bash
+# Verificar estado de sincronización en todos los nodos
+edge-cli sync status --fleet-wide --format table
+
+# Salida:
+# NODE           LAST_SYNC    LAG     STATUS
+# edge-node-01   2026-06-23   2s      healthy
+# edge-node-02   2026-06-23   45s     degraded
+# edge-node-03   2026-06-22   4h      offline
+```
+
+### Estrategias de Sincronización
+
+| Estrategia | Caso de Uso | Consistencia | Rendimiento |
+|------------|-------------|--------------|-------------|
+| Basada en envío | Activos estáticos | Fuerte | Alto ancho de banda |
+| Basada en solicitud | Contenido dinámico | Eventual | Bajo demanda |
+| Híbrida | Cargas de trabajo mixtas | Ajustable | Equilibrado |
+
+## Medición de Latencia (Presupuesto de 200ms)
+
+La latencia de extremo a extremo se mende desde la solicitud del cliente hasta la entrega de la respuesta.
+
+### Puntos de Medición
+
+1. **Cliente → Nodo del borde**: Resolución DNS +握手 TCP + TLS
+2. **Procesamiento del borde**: Tiempo de ejecución de la función
+3. **Borde → Origen** (en caso de fallo): Penalización por fallo de caché
+4. **Entrega de respuesta**: Serialización + transferencia
+
+### Desglose del Presupuesto de Latencia
+
+| Segmento | Presupuesto | Actual | Estado |
+|----------|-------------|--------|--------|
+| Resolución DNS | 20ms | 12ms | [PASS] |
+| Handshake TLS | 40ms | 35ms | [PASS] |
+| Procesamiento del borde | 50ms | 42ms | [PASS] |
+| Fallo de caché (p95) | 80ms | 78ms | [PASS] |
+| Sobrecarga de transferencia | 10ms | 8ms | [PASS] |
+| **Total** | **200ms** | **175ms** | **[PASS]** |
+
+### Reglas de Alerta
+
+```yaml
+alerts:
+  - name: edge-latency-p99
+    condition: latency_p99 > 200ms
+    severity: critical
+    action: page-oncall
+  - name: edge-latency-p95
+    condition: latency_p95 > 180ms
+    severity: warning
+    action: notify-slack
+```
+
+## Operaciones sin Conexión (Ref: EC-R02)
+
+Los nodos del borde deben continuar sirviendo contenido en caché cuando se desconectan del origen.
+
+### Matriz de Capacidades sin Conexión
+
+| Capacidad | Disponible sin Conexión | Sincronización Requerida |
+|-----------|-------------------------|--------------------------|
+| Lectura de contenido en caché | Sí | No |
+| Servir activos estáticos | Sí | No |
+| Ejecutar funciones del borde | Sí (en caché) | Al reconectar |
+| Operaciones de escritura | En cola local | Sincronización en segundo plano |
+| Autenticación | Tokens en caché | Actualizar al reconectar |
+
+### Detección sin Conexión
+
+```bash
+# Monitorear conectividad con el origen
+edge-cli connectivity monitor \
+  --interval 5s \
+  --threshold 3 failures \
+  --action enter-offline-mode
+```
+
+## Gestión de Flota
+
+### Actualizaciones Escalonadas
+
+```bash
+# Actualizar flota en incrementos del 10%
+edge-cli fleet update \
+  --image edge-runtime:2.4.1 \
+  --strategy rolling \
+  --batch-size 10% \
+  --pause-on-failure-rate 5%
+```
+
+### Planificación de Capacidad
+
+```bash
+# Ver resumen de capacidad de la flota
+edge-cli fleet capacity --format json
+
+# Métricas clave:
+# - Nodos totales: 24
+# - Capacidad de cómputo activa: 96 vCPUs
+# - Capacidad de almacenamiento: 1.2Ti
+# - Utilización actual: 62%
+```
+
+---
+[Volver al Perfil de Computación en el Borde](./README.es.md)

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

@@ -0,0 +1,148 @@
+# Edge Computing — Operations Guide
+
+> **Bilingual Navigation:** [English](./operations.md) | [Español](./operations.es.md)
+
+**Owner:** Platform Engineering
+**Topology:** Edge Computing
+
+## Node Lifecycle Management
+
+Edge nodes follow a defined lifecycle: provisioning, registration, activation, monitoring, maintenance, and decommissioning.
+
+### Provisioning
+
+```bash
+# Register a new edge node
+edge-cli node register \
+  --node-id edge-node-01 \
+  --region us-west-2 \
+  --zone us-west-2a \
+  --role compute \
+  --capacity "cpu=4,memory=8Gi,storage=50Gi"
+```
+
+### Health Monitoring
+
+Each node reports health metrics every 15 seconds:
+
+| Metric | Threshold | Action on Breach |
+|--------|-----------|------------------|
+| Latency to origin | > 200ms | Trigger failover |
+| CPU utilization | > 85% | Shed non-critical workloads |
+| Memory usage | > 90% | Evict least-recently-used cache |
+| Disk usage | > 80% | Purge stale content |
+| Sync lag | > 30s | Escalate to operations |
+
+## Content Sync Monitoring (Ref: EC-R01)
+
+The sync strategy ensures content consistency across the edge fleet.
+
+### Sync Health Dashboard
+
+```bash
+# Check sync status across all nodes
+edge-cli sync status --fleet-wide --format table
+
+# Output:
+# NODE           LAST_SYNC    LAG     STATUS
+# edge-node-01   2026-06-23   2s      healthy
+# edge-node-02   2026-06-23   45s     degraded
+# edge-node-03   2026-06-22   4h      offline
+```
+
+### Sync Strategies
+
+| Strategy | Use Case | Consistency | Performance |
+|----------|----------|-------------|-------------|
+| Push-based | Static assets | Strong | High bandwidth |
+| Pull-based | Dynamic content | Eventual | On-demand |
+| Hybrid | Mixed workloads | Tunable | Balanced |
+
+## Latency Measurement (200ms Budget)
+
+End-to-end latency is measured from client request to response delivery.
+
+### Measurement Points
+
+1. **Client → Edge Node**: DNS resolution + TCP handshake + TLS
+2. **Edge Processing**: Function execution time
+3. **Edge → Origin** (on miss): Cache miss penalty
+4. **Response Delivery**: Serialization + transfer
+
+### Latency Budget Breakdown
+
+| Segment | Budget | Current | Status |
+|---------|--------|---------|--------|
+| DNS resolution | 20ms | 12ms | [PASS] |
+| TLS handshake | 40ms | 35ms | [PASS] |
+| Edge processing | 50ms | 42ms | [PASS] |
+| Cache miss (p95) | 80ms | 78ms | [PASS] |
+| Transfer overhead | 10ms | 8ms | [PASS] |
+| **Total** | **200ms** | **175ms** | **[PASS]** |
+
+### Alerting Rules
+
+```yaml
+alerts:
+  - name: edge-latency-p99
+    condition: latency_p99 > 200ms
+    severity: critical
+    action: page-oncall
+  - name: edge-latency-p95
+    condition: latency_p95 > 180ms
+    severity: warning
+    action: notify-slack
+```
+
+## Offline Operations (Ref: EC-R02)
+
+Edge nodes must continue serving cached content when disconnected from origin.
+
+### Offline Capability Matrix
+
+| Capability | Available Offline | Sync Required |
+|------------|-------------------|---------------|
+| Read cached content | Yes | No |
+| Serve static assets | Yes | No |
+| Execute edge functions | Yes (cached) | On reconnect |
+| Write operations | Queued locally | Background sync |
+| Authentication | Cached tokens | Refresh on reconnect |
+
+### Offline Detection
+
+```bash
+# Monitor origin connectivity
+edge-cli connectivity monitor \
+  --interval 5s \
+  --threshold 3 failures \
+  --action enter-offline-mode
+```
+
+## Fleet Management
+
+### Rolling Updates
+
+```bash
+# Update fleet in 10% increments
+edge-cli fleet update \
+  --image edge-runtime:2.4.1 \
+  --strategy rolling \
+  --batch-size 10% \
+  --pause-on-failure-rate 5%
+```
+
+### Capacity Planning
+
+```bash
+# View fleet capacity summary
+edge-cli fleet capacity --format json
+
+# Key metrics:
+# - Total nodes: 24
+# - Active compute capacity: 96 vCPUs
+# - Storage capacity: 1.2Ti
+# - Current utilization: 62%
+```
+
+---
+[Back to Edge Computing Profile](./README.md)

package/rulesets/topologies/edge-computing/parity-fixtures/compliant.json

@@ -0,0 +1,12 @@
+{
+  "input": {
+    "topology": "edge-computing",
+    "config": {
+      "networkSecurity": { "mtlsEnabled": true },
+      "syncStrategy": "offline-first",
+      "edgeIsolation": true,
+      "conflictResolution": "last-write-wins"
+    }
+  },
+  "expectedNative": []
+}

package/rulesets/topologies/edge-computing/parity-fixtures/violation.json

@@ -0,0 +1,13 @@
+{
+  "input": {
+    "topology": "edge-computing",
+    "config": {
+      "networkSecurity": { "mtlsEnabled": true },
+      "edgeIsolation": true,
+      "conflictResolution": "last-write-wins"
+    }
+  },
+  "expectedNative": [
+    { "ruleId": "EC-R01", "severity": "error", "file": null }
+  ]
+}