eva4j 1.0.16 → 1.0.17

package/src/skills/build-system-yaml/SKILL.md

@@ -62,11 +62,32 @@ Si el usuario no proveyó todos los datos, **pregunta** antes de generar:
 3. **Endpoints REST** por módulo (método + path + caso de uso)
 4. **Flujos async**: evento → productor → consumidores + `useCase` de cada consumidor
 5. **Llamadas sync**: caller → destino → endpoints usados
+6. **Dependencias de datos cross-module**: ¿algún módulo necesita datos de otro para validar o enriquecer? → candidato a **Read Model** (proyección local mantenida por eventos) en vez de llamada sync
 
 > Si `system/system.yaml` ya existe, léelo y pregunta solo por cambios.
 
 Aplica el rol funcional: sugiere módulos necesarios no mencionados, propone flujos async coherentes, anticipa invariantes. Confirma antes de agregar elementos no solicitados.
 
+### Read Models — decisión de diseño
+
+Cuando un módulo necesita datos de otro módulo, evalúa antes de decidir entre `ports:` (sync HTTP) y `readModels:` (async, proyección local):
+
+| Pregunta | Si la respuesta es SÍ → |
+|---|---|
+| ¿El dato se consulta en cada request o en operaciones frecuentes? | `readModels:` |
+| ¿Se tolera consistencia eventual (ms de delay)? | `readModels:` |
+| ¿Se prepara el sistema para microservicios (`eva detach`)? | `readModels:` |
+| ¿Se necesita consistencia fuerte (ej: saldo financiero)? | `ports:` |
+| ¿Es una llamada infrecuente y simple (ej: lookup puntual)? | `ports:` |
+
+**Patrón típico:** Si un módulo ya consume eventos de otro módulo (`listeners:`) y además llama sync para obtener datos del mismo módulo (`ports:`), es candidato fuerte a reemplazar el port por un readModel.
+
+Si decides usar readModel:
+1. En `system.yaml`: declarar eventos con `consumers[].readModel:` en vez de `useCase:`
+2. En `{module}.yaml`: declarar `readModels:` con `source`, `tableName`, `fields`, `syncedBy`
+3. Eliminar la entrada `integrations.sync[]` que reemplaza
+4. Asegurar que el módulo fuente emita los eventos necesarios en sus `events:` — usar `lifecycle:` para eventos CRUD (`create`/`update`/`delete`/`softDelete`) en vez de `triggers:`
+
 ---
 
 ## Paso 2 — Estructura del system.yaml
@@ -108,6 +129,13 @@ integrations:
       consumers:
         - module: payments
           useCase: HandleOrderPlaced
+    # Read Model sync — usa readModel: en vez de useCase:
+    - event: ProductCreatedEvent
+      producer: products
+      topic: PRODUCT_CREATED
+      consumers:
+        - module: orders
+          readModel: ProductReadModel    # proyección local de datos cross-module
   sync:
     - caller: orders
       calls: customers
@@ -134,6 +162,8 @@ integrations:
 - Sin port names genéricos compartidos entre módulos
 - `consumers[].useCase` siempre presente y en PascalCase
 - `calls.using:` solo referencia endpoints de `exposes:` del destino
+- Cada consumer declara exactamente `useCase:` (lógica de negocio) o `readModel:` (proyección local), nunca ambos
+- `readModel:` PascalCase + sufijo `ReadModel` — su módulo consumidor declara `readModels:` en domain.yaml
 
 ---
 
@@ -146,6 +176,8 @@ Antes de proponer el `system.yaml`, verifica:
 - [ ] Sin dependencias circulares síncronas
 - [ ] Todos los `consumers[].module` existen en `modules:`
 - [ ] Todos los `consumers[].useCase` presentes y en PascalCase
+- [ ] `consumers[]` con `readModel:` en PascalCase + sufijo `ReadModel`
+- [ ] Cada consumer tiene exactamente `useCase:` o `readModel:`, nunca ambos
 - [ ] Todos los `calls.using:` existen en `exposes:` del destino
 - [ ] Módulos pasivos no son `caller`
 - [ ] Todo en inglés
@@ -257,6 +289,7 @@ C4Container
 - `ContainerQueue()` para el broker — solo si `messaging.enabled: true`; usar el tipo de `messaging.broker`
 - `System_Ext()` fuera del boundary para servicios externos
 - **Flechas async siempre pasan por el broker**: `producer → broker` y `broker → consumer`, nunca directo
+- **Read Model sync también pasa por el broker**: `Rel(source, broker, "ProductCreatedEvent", "Kafka")` + `Rel(broker, consumer, "Sync ProductReadModel", "Kafka")` — no usar flecha directa
 - **Flechas sync** directas entre containers: de caller a callee con label del port name
 - Los `Rel()` de eventos incluyen el nombre del evento en el campo `technology`/label
 - Derivar actores `Person()` de quienes consumen los `exposes[]`
@@ -302,7 +335,95 @@ Antes de guardar, verifica:
 
 Lee `references/domain-yaml-spec.md` para la especificación completa de estructura, reglas, restricciones y checklist del `system/{module}.yaml`.
 
-Para cada módulo en `modules:`, genera `system/{nombre-del-modulo}.yaml` con: aggregates, entities, valueObjects, enums (con transitions si aplica), events, endpoints, listeners y ports — todo inferido del `system.yaml`.
+Para cada módulo en `modules:`, genera `system/{nombre-del-modulo}.yaml` con: aggregates, entities, valueObjects, enums (con transitions si aplica), events, endpoints, listeners, ports y **readModels** — todo inferido del `system.yaml`.
+
+### Inferencia de readModels desde system.yaml
+
+Cuando `integrations.async[].consumers[]` tiene `readModel:` y el `module` es el módulo actual:
+1. Agrupar todos los eventos del mismo `readModel:` → una entrada `readModels:` con múltiples `syncedBy`
+2. `source.module` = el `producer` de esas integraciones async
+3. `source.aggregate` = derivar del nombre del readModel (ej: `ProductReadModel` → `Product`)
+4. `tableName` = `rm_` + snake_case del source module (ej: `rm_products`)
+5. `fields` = inferir del payload del evento fuente (incluir siempre `id`)
+6. `syncedBy[].action` = `UPSERT` para Created/Updated, `SOFT_DELETE` para Deactivated, `DELETE` para Deleted
+7. Si había una entrada `integrations.sync[]` al mismo módulo fuente → **no generar `ports:`** para esa llamada (el readModel la reemplaza)
+
+### Lifecycle events en módulos fuente
+
+Cuando el módulo actual es `producer` en `integrations.async[]` y algún consumer tiene `readModel:`, los eventos de este módulo deben usar `lifecycle:` (operación CRUD) en vez de `triggers:` (transición de estado).
+
+Para cada evento de este módulo consumido por un readModel:
+
+1. Agregar `lifecycle:` al evento — derivar el valor del nombre del evento:
+   | Patrón del nombre | `lifecycle:` |
+   |---|---|
+   | `*CreatedEvent`, `*RegisteredEvent` | `create` |
+   | `*UpdatedEvent` | `update` |
+   | `*DeletedEvent` | `delete` |
+   | `*DeactivatedEvent` | `softDelete` |
+
+2. **NO** agregar `triggers:` — estos eventos son CRUD, no transiciones de estado
+3. Si `lifecycle: softDelete` → la entidad raíz **debe** tener `hasSoftDelete: true`
+4. Si `lifecycle: delete` → la entidad raíz **NO debe** tener `hasSoftDelete: true`
+5. `fields:` del evento debe incluir **todos** los campos declarados en el `readModels[].fields` del módulo consumidor (el payload es la fuente de verdad de la proyección)
+6. Siempre incluir `{entityName}Id` como campo (se mapea a `aggregateId` del DomainEvent base)
+7. `fields:` del lifecycle event solo puede contener: (a) `{entityName}Id` (aggregateId), (b) campos que existen en la entidad raíz, (c) campos temporales `*At` + `LocalDateTime`. No incluir campos que no existan en la entidad — genera error `C2-010`
+8. Los campos de los readModels consumidores deben ser subconjunto de los campos de la entidad raíz del productor. Si el readModel necesita un campo, ese campo debe existir en la entidad fuente — de lo contrario los lifecycle events no podrán emitirlo (C2-010) y el campo siempre será null (C1-007)
+
+**Ejemplo — módulo `products` como fuente de `ProductReadModel`:**
+
+```yaml
+aggregates:
+  - name: Product
+    entities:
+      - name: product
+        isRoot: true
+        tableName: products
+        hasSoftDelete: true
+        audit:
+          enabled: true
+        fields:
+          - name: id
+            type: String
+          - name: name
+            type: String
+          - name: price
+            type: BigDecimal
+          - name: status
+            type: String
+            readOnly: true
+            defaultValue: "ACTIVE"
+    events:
+      - name: ProductCreatedEvent
+        lifecycle: create
+        fields:
+          - name: productId
+            type: String
+          - name: name
+            type: String
+          - name: price
+            type: BigDecimal
+          - name: status
+            type: String
+      - name: ProductUpdatedEvent
+        lifecycle: update
+        fields:
+          - name: productId
+            type: String
+          - name: name
+            type: String
+          - name: price
+            type: BigDecimal
+          - name: status
+            type: String
+      - name: ProductDeactivatedEvent
+        lifecycle: softDelete
+        fields:
+          - name: productId
+            type: String
+          - name: deactivatedAt
+            type: LocalDateTime
+```
 
 ---
 

package/src/skills/build-system-yaml/references/domain-yaml-spec.md

@@ -32,6 +32,14 @@ Propón campos necesarios no mencionados, Value Objects expresivos, invariantes
 11. ❌ **Todo en inglés**
 12. ❌ **No transiciones sin evidencia de activación** — toda transición activada por `ports:` o scheduler necesita un domain event con `triggers`
 13. ❌ **No reutilizar `service:` en `ports[]` entre módulos** — nombres propios del bounded context
+14. ❌ **No `readModels[].source.module` igual al módulo actual** — readModels son cross-module exclusivamente
+15. ❌ **No auditoría, endpoints REST ni lógica de negocio en `readModels:`** — son proyecciones inmutables
+16. ❌ **No `readModels[].name` sin sufijo `ReadModel`** — siempre `PascalCase + ReadModel`
+17. ❌ **No `readModels[].tableName` sin prefijo `rm_`** — identificación visual obligatoria
+18. ❌ **No `lifecycle:` y `triggers:` en el mismo evento** — son mutuamente excluyentes
+19. ❌ **No `lifecycle: softDelete` sin `hasSoftDelete: true`** en la entidad raíz
+20. ❌ **No `lifecycle: delete` con `hasSoftDelete: true`** — delete es hard delete
+21. ❌ **No declarar campos en lifecycle events que no existan en la entidad raíz** — solo `{entityName}Id`, campos de la entidad y campos temporales auto-resolubles (`*At` + `LocalDateTime`). Genera error `C2-010`
 
 ---
 
@@ -41,7 +49,8 @@ Propón campos necesarios no mencionados, Value Objects expresivos, invariantes
 |---|---|
 | `modules[x].exposes[]` | `endpoints:` con `basePath` + `versions[].operations[]` |
 | `integrations.async[]` donde `producer = módulo` | `events:` |
-| `integrations.async[].consumers[]` donde `module = módulo` | `listeners:` (con `useCase`) |
+| `integrations.async[].consumers[]` donde `module = módulo` y tiene `useCase` | `listeners:` (con `useCase`) |
+| `integrations.async[].consumers[]` donde `module = módulo` y tiene `readModel` | `readModels:` (con `syncedBy`) |
 | `integrations.sync[]` donde `caller = módulo` | `ports:` (con `service`, `http`) |
 
 ### Formato correcto de endpoints
@@ -176,6 +185,35 @@ aggregates:
           - name: reason
             type: String
 
+      # ── Lifecycle events (CRUD-based, no transitions) ──
+      # Use lifecycle: instead of triggers: when the event is emitted
+      # at a CRUD operation (create/update/delete/softDelete).
+      # Typical use: source modules whose events feed readModels.
+      #
+      # - name: ProductCreatedEvent
+      #   lifecycle: create          # raise() in creation constructor
+      #   fields:
+      #     - name: productId
+      #       type: String
+      #     - name: name
+      #       type: String
+      #
+      # - name: ProductUpdatedEvent
+      #   lifecycle: update          # raise() in UpdateCommandHandler
+      #   fields: [...]
+      #
+      # - name: ProductDeletedEvent
+      #   lifecycle: delete          # raise() in DeleteCommandHandler
+      #   fields:
+      #     - name: productId
+      #       type: String
+      #
+      # - name: ProductDeactivatedEvent
+      #   lifecycle: softDelete      # raise() in softDelete() method
+      #   fields:
+      #     - name: productId
+      #       type: String
+
 endpoints:
   basePath: /orders
   versions:
@@ -289,34 +327,164 @@ Anotaciones: `NotNull`, `NotBlank`, `NotEmpty`, `Email`, `Size`, `Min`, `Max`, `
 
 ---
 
-## Proyecciones locales (read models)
+## Proyecciones locales (`readModels:`)
+
+Cuando un módulo necesita datos de otro bounded context para validar precondiciones o enriquecer entidades, usar `readModels:` en vez de `ports:` (sync HTTP). Esto elimina dependencias síncronas y mejora autonomía, resiliencia y rendimiento.
 
-Agregados sincronizados por listeners Kafka. Señales:
-- Campos coinciden con `listeners[].fields`
-- useCase: `Register*InLocalCatalog`, `Sync*`, `Update*FromEvent`
-- Sin endpoints de escritura
-- Existe para evitar llamadas síncronas en tiempo real
+### Cuándo usar readModels vs ports
+
+| Criterio | `readModels:` (async) | `ports:` (sync) |
+|---|---|---|
+| Consistencia eventual aceptable | ✅ | — |
+| Se necesita consistencia fuerte | — | ✅ |
+| Datos se consultan frecuentemente | ✅ | — |
+| Llamada infrecuente y simple | — | ✅ |
+| Preparación para microservicios | ✅ | — |
 
-**Auditoría:** `audit.enabled: true`, `trackUser: false` (cambios vienen de eventos, no de usuarios).
+### Estructura
 
 ```yaml
-- name: BikeCatalog
-  entities:
-    - name: bikeCatalogEntry
-      isRoot: true
-      tableName: bike_catalog_entries
-      audit:
-        enabled: true
-        trackUser: false
-      fields:
-        - name: id
-          type: String
-        - name: isAvailable
-          type: Boolean
-          readOnly: true
-          defaultValue: true
+# Nivel raíz, sibling de aggregates:, listeners:, ports:
+readModels:
+  - name: ProductReadModel               # PascalCase + sufijo "ReadModel" (OBLIGATORIO)
+    source:                              # Trazabilidad al módulo fuente (OBLIGATORIO)
+      module: products                   # Módulo fuente (kebab-case)
+      aggregate: Product                 # Agregado fuente (PascalCase)
+    tableName: rm_products               # Tabla en BD (OBLIGATORIO, prefijo rm_)
+    fields:                              # Campos proyectados — subconjunto del fuente
+      - name: id
+        type: String
+      - name: name
+        type: String
+      - name: price
+        type: BigDecimal
+      - name: status
+        type: String
+    syncedBy:                            # Eventos que mantienen esta tabla (min 1)
+      - event: ProductCreatedEvent       # Nombre del evento (PascalCase + sufijo Event)
+        action: UPSERT                   # Acción: UPSERT | DELETE | SOFT_DELETE
+      - event: ProductUpdatedEvent
+        action: UPSERT
+      - event: ProductDeactivatedEvent
+        action: SOFT_DELETE
 ```
 
+### Reglas
+
+- **`name:`** — PascalCase, **DEBE** terminar con `ReadModel`
+- **`tableName:`** — **DEBE** empezar con `rm_` (identificación visual en BD)
+- **`fields:`** — **DEBE** incluir un campo `id`
+- **`syncedBy:`** — **DEBE** tener al menos una entrada
+- **`source.module:`** — **NO PUEDE** ser el mismo módulo actual (cross-module exclusivamente)
+- **Sin auditoría** — Los readModels **nunca** tienen campos de auditoría
+- **Sin endpoints REST** — Los readModels **nunca** exponen endpoints
+- **Sin lógica de negocio** — La clase de dominio es inmutable (solo getters)
+
+### Acciones de sincronización
+
+| Acción | Significado | Uso |
+|---|---|---|
+| `UPSERT` | Insertar si es nuevo, actualizar si existe | Creaciones, actualizaciones, cambios de estado |
+| `DELETE` | Eliminar el registro permanentemente | Hard deletes en el módulo fuente |
+| `SOFT_DELETE` | Marcar como inactivo con timestamp | Cuando el fuente usa soft delete |
+
+### Inferencia desde system.yaml
+
+| Fuente en system.yaml | Destino en domain.yaml |
+|---|---|
+| `consumers[].readModel: ProductReadModel` | `readModels:` entry con ese nombre |
+| `integrations.async[].producer` | `readModels[].source.module` |
+| `integrations.async[].topic` | Topic derivado automáticamente del nombre del evento |
+
+### Impacto en el módulo fuente
+
+El módulo fuente **debe** emitir los eventos referenciados en `syncedBy`. Asegurar que los `events:` del fuente incluyan todos los campos declarados en `readModels[].fields` (el payload es la fuente de verdad para la proyección).
+
+**Restricción de cobertura:** Los campos del readModel (excepto `id`) deben estar cubiertos por al menos un evento UPSERT en `syncedBy[]`. Si un campo no aparece en ningún evento UPSERT, siempre será null — genera warning `C1-007`. Además, los campos del readModel deben ser subconjunto de los campos de la entidad raíz del módulo fuente (por C2-010, los lifecycle events no pueden emitir campos ajenos a la entidad).
+
+### Propiedad `lifecycle:` en eventos del módulo fuente
+
+Cuando un evento existe para alimentar un readModel (operación CRUD pura, sin transición de estado), usar `lifecycle:` en vez de `triggers:`.
+
+| Valor | Punto de emisión | Descripción |
+|---|---|---|
+| `create` | Constructor de creación de la entidad | UUID auto-generado como id antes de raise() |
+| `update` | UpdateCommandHandler, antes de `repository.save()` | raise() sobre la entidad reconstruida |
+| `delete` | DeleteCommandHandler, antes de `repository.delete()` | Hard delete — requiere `hasSoftDelete` ausente o false |
+| `softDelete` | Método `softDelete()` de la entidad | Requiere `hasSoftDelete: true` en la entidad raíz |
+
+**Derivación desde el nombre del evento:**
+
+| Patrón del nombre del evento | `lifecycle:` |
+|---|---|
+| `*CreatedEvent`, `*RegisteredEvent` | `create` |
+| `*UpdatedEvent` | `update` |
+| `*DeletedEvent` | `delete` |
+| `*DeactivatedEvent` | `softDelete` |
+
+**Ejemplo — módulo fuente `products`:**
+
+```yaml
+aggregates:
+  - name: Product
+    entities:
+      - name: product
+        isRoot: true
+        tableName: products
+        hasSoftDelete: true              # requerido por lifecycle: softDelete
+        audit:
+          enabled: true
+        fields:
+          - name: id
+            type: String
+          - name: name
+            type: String
+          - name: price
+            type: BigDecimal
+          - name: status
+            type: String
+            readOnly: true
+            defaultValue: "ACTIVE"
+    events:
+      - name: ProductCreatedEvent
+        lifecycle: create
+        fields:
+          - name: productId
+            type: String
+          - name: name
+            type: String
+          - name: price
+            type: BigDecimal
+          - name: status
+            type: String
+      - name: ProductUpdatedEvent
+        lifecycle: update
+        fields:
+          - name: productId
+            type: String
+          - name: name
+            type: String
+          - name: price
+            type: BigDecimal
+          - name: status
+            type: String
+      - name: ProductDeactivatedEvent
+        lifecycle: softDelete
+        fields:
+          - name: productId
+            type: String
+          - name: deactivatedAt
+            type: LocalDateTime
+```
+
+**Reglas:**
+- `lifecycle:` y `triggers:` son mutuamente excluyentes — un evento usa uno u otro, nunca ambos
+- `lifecycle: softDelete` requiere `hasSoftDelete: true` en la entidad raíz
+- `lifecycle: delete` requiere que `hasSoftDelete` sea `false` o esté ausente
+- `fields:` del evento debe incluir **todos** los campos del readModel que lo consume (el payload es la fuente de verdad para la proyección)
+- Siempre incluir `{entityName}Id` como campo (se mapea a `aggregateId` del DomainEvent base)
+- `fields:` del lifecycle event solo puede contener: (a) `{entityName}Id`, (b) campos que existen en la entidad raíz del agregado, (c) campos temporales auto-resolubles (nombre termina en `At` + tipo `LocalDateTime`). Cualquier otro campo genera error `C2-010`
+
 ---
 
 ## Clasificación de campos readOnly
@@ -406,5 +574,18 @@ Si un valor no es trazable → falta un endpoint o listener en el diseño.
 - [ ] `nestedTypes[]` para campos de tipo objeto en listeners/ports
 - [ ] Transiciones por `ports:` tienen domain event con `triggers`
 - [ ] Cada enum `*Type` valor trazable a listener/endpoint/event
-- [ ] Proyecciones: `audit.enabled: true`, `trackUser: false`
+- [ ] Proyecciones cross-module: usar `readModels:` con `source`, `tableName` (prefijo `rm_`), `fields` (incluye `id`), `syncedBy`
+- [ ] `readModels[].name` termina con `ReadModel` (PascalCase)
+- [ ] `readModels[].source.module` ≠ módulo actual
+- [ ] `readModels[].syncedBy` → al menos una entrada con `action` válida (UPSERT, DELETE, SOFT_DELETE)
+- [ ] Eventos en `syncedBy` deben existir como `events:` en el módulo fuente
+- [ ] Eventos del módulo fuente consumidos por readModels → deben tener `lifecycle:` (no `triggers:`)
+- [ ] `lifecycle:` derivado del nombre del evento: `*CreatedEvent`→`create`, `*UpdatedEvent`→`update`, `*DeletedEvent`→`delete`, `*DeactivatedEvent`→`softDelete`
+- [ ] `lifecycle: softDelete` → entidad raíz tiene `hasSoftDelete: true`
+- [ ] `lifecycle: delete` → entidad raíz NO tiene `hasSoftDelete: true`
+- [ ] `lifecycle:` y `triggers:` nunca en el mismo evento
+- [ ] Lifecycle event fields son campos de la entidad raíz (excluyendo `{entityName}Id` y `*At` temporal) — `C2-010`
+- [ ] ReadModel fields cubiertos por eventos UPSERT del productor — `C1-007`
+- [ ] ReadModel fields son subconjunto de los campos de la entidad raíz fuente
+- [ ] Si `readModels:` reemplaza un `ports:`, eliminar la entrada sync correspondiente
 - [ ] Todo en inglés

package/src/skills/build-system-yaml/references/module-spec.md

@@ -61,6 +61,17 @@ Especificación técnica narrativa del sistema completo. Una sección `##` por c
 **When called:** [in which use case and under what condition]
 **Endpoints used:** [METHOD /path list]
 **Data obtained and how it's used:** [detailed description]
+
+### Read Models (local projections)
+[Only if module has readModels: in its domain.yaml]
+
+#### {ReadModelName} ← {source-module}
+**Purpose:** [why this projection exists — what data it provides and why sync HTTP was replaced]
+**Source aggregate:** [{Aggregate} in {source-module}]
+**Table:** [{tableName}]
+**Projected fields:** [field list with types]
+**Synced by:** [event names and actions (UPSERT/DELETE/SOFT_DELETE)]
+**Consistency model:** Eventual — acceptable delay: [specify, e.g. "milliseconds"]
 ```
 
 ### Reglas del system.md
@@ -245,6 +256,27 @@ flowchart TD
 **When called:** [in which use case and condition]
 **Endpoints used:** [METHOD /path list]
 **Data obtained and how it's used:** [detailed description]
+
+## Read Models (local projections)
+[Only if module has readModels: in its domain.yaml]
+
+### {ReadModelName} ← {source-module}
+**Purpose:** [why this projection exists — what data it provides and why sync HTTP was not used]
+**Source aggregate:** [{Aggregate} in {source-module}]
+**Table:** [{tableName}]
+**Projected fields:** [field list with types and business meaning]
+**Synced by:** [event name → action, for each syncedBy entry]
+**Consistency model:** Eventual — acceptable delay: [specify]
+**Replaces:** [sync port name, if applicable — e.g., "Replaces OrderProductService sync call"]
+
+### Architectural Decision — {ReadModelName}
+
+**Context:** [{module} needs {data description} from {source-module} to {business reason}]
+**Decision:** Use event-driven Local Read Model instead of sync HTTP call.
+**Consequences:**
+- (+) Module is fully autonomous — no runtime dependency on {source-module}
+- (+) Lower latency — local DB query vs HTTP roundtrip
+- (-) Eventual consistency — milliseconds delay on updates
 ```
 
 ---
@@ -253,7 +285,7 @@ flowchart TD
 
 - **Todo en inglés**: títulos, secciones, descripciones, invariantes, use cases.
 - **INVARIANTES obligatorias**: al menos 2–3 por módulo. Analizar unicidad, estados válidos, rangos, precondiciones de transición.
-- **Diagrama de interacciones obligatorio**: todos los endpoints y eventos entrantes. Sin entradas → nodo `[[passive module]]`.
+- **Diagrama de interacciones obligatorio**: todos los endpoints, eventos entrantes y read models. Sin entradas → nodo `[[passive module]]`. Read models se muestran como subgraphs separados con label `Read Models` y nodos `📦 {ReadModelName}` conectados desde eventos de sincronización.
 - **Diagrama de secuencia obligatorio**: al menos un `sequenceDiagram` cubriendo el happy path. Diagramas adicionales para bifurcaciones (error, compensación). Modelar todos los actores reales.
 - **Diagrama de flujo por caso de uso**: `flowchart TD` dentro de cada `### {UseCase}` con trigger, invariantes, lógica y eventos.
 - **Máquina de estados condicional**: solo si hay entidades con ciclo de vida. Restricciones de transición son invariantes implícitas.

package/src/skills/build-system-yaml/references/system-yaml-spec.md

@@ -58,6 +58,14 @@ integrations:
         - module: notifications
           useCase: NotifyOrderPlaced   # acción que notifications ejecuta
 
+    # Read Model sync — consumer usa readModel: en vez de useCase:
+    - event: ProductCreatedEvent
+      producer: products
+      topic: PRODUCT_CREATED
+      consumers:
+        - module: orders
+          readModel: ProductReadModel  # ← indica sync de read model, no lógica de negocio
+
   sync:
     - caller: orders               # módulo que hace la llamada
       calls: customers             # módulo destino
@@ -78,6 +86,7 @@ integrations:
 | Port names | PascalCase + sufijo `Service` — **único por módulo** | `OrderCustomerService` | `CustomerService` (compartido) |
 | useCases | PascalCase, verbo + sustantivo | `CreateOrder`, `FindAllOrders` | `createOrder`, `orders` |
 | `consumers[].useCase` | PascalCase, verbo + sustantivo | `HandleOrderPlaced` | `orderPlaced` |
+| `consumers[].readModel` | PascalCase + `ReadModel` | `ProductReadModel` | `productReadModel` |
 
 ---
 
@@ -91,6 +100,31 @@ integrations:
 - ✅ `consumers[].module` debe existir en `modules:`
 - ✅ Módulos pasivos (notificaciones, auditoría) son **consumidores**, nunca `caller`
 - ℹ️ Varios módulos pueden consumir el mismo evento sin riesgo de colisión de beans
+- ℹ️ `consumers[]` puede usar `readModel:` en vez de `useCase:` para indicar sync de Read Model local (proyección de datos cross-module mantenida por eventos)
+
+---
+
+## Consumers: useCase vs readModel
+
+Cada entrada en `consumers[]` debe declarar **exactamente uno** de:
+
+| Campo | Cuándo usar | Qué genera en domain.yaml |
+|---|---|---|
+| `useCase:` | Lógica de negocio (handler + command) | `listeners:` entry |
+| `readModel:` | Proyección local de datos (sync handler) | `readModels:` entry con `syncedBy` |
+
+```yaml
+consumers:
+  - module: payments
+    useCase: HandleOrderPlaced       # → listeners: en payments.yaml
+  - module: orders
+    readModel: ProductReadModel      # → readModels: en orders.yaml
+```
+
+**Reglas de `readModel:`:**
+- PascalCase, sufijo `ReadModel`
+- El module consumidor declara `readModels:` en su `domain.yaml` con `source.module` apuntando al producer
+- Al reemplazar un port sync por un readModel, eliminar la entrada de `integrations.sync[]`
 
 ---
 
@@ -170,6 +204,8 @@ consumers:
 - [ ] Sin dependencias circulares síncronas
 - [ ] Todos los `consumers[].module` existen en `modules:`
 - [ ] Todos los `consumers[].useCase` presentes y en PascalCase
+- [ ] `consumers[]` con `readModel:` usan PascalCase + sufijo `ReadModel`
+- [ ] Cada consumer tiene exactamente uno de `useCase:` o `readModel:` (nunca ambos)
 - [ ] Todos los `calls.using:` existen en `exposes:` del destino
 - [ ] Módulos pasivos no son `caller`
 - [ ] `useCases` en PascalCase

package/src/utils/config-manager.js

@@ -1,5 +1,6 @@
 const fs = require('fs-extra');
 const path = require('path');
+const { toCamelCase } = require('./naming');
 
 class ConfigManager {
   constructor(projectPath = process.cwd()) {
@@ -88,8 +89,9 @@ class ConfigManager {
   async moduleExists(moduleName) {
     const config = await this.loadProjectConfig();
     if (!config) return false;
-    
-    return config.modules.some(module => module.name === moduleName);
+
+    const normalized = toCamelCase(moduleName);
+    return config.modules.some(module => module.name === normalized);
   }
 
   /**