eva4j 1.0.16 → 1.0.17

package/src/utils/domain-validator.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const { pluralizeWord } = require('./naming');
+const { pluralizeWord, singularizeWord } = require('./naming');
 
 /**
  * Domain-level validator for eva evaluate system --domain
@@ -119,7 +119,10 @@ function buildSystemAsyncMap(systemConfig) {
     map[ev.event] = {
       producer: ev.producer,
       topic: ev.topic,
-      consumers: (ev.consumers || []).map((c) => (typeof c === 'string' ? c : c.module)),
+      consumers: (ev.consumers || []).map((c) => {
+        if (typeof c === 'string') return { module: c, useCase: undefined, readModel: undefined };
+        return { module: c.module, useCase: c.useCase, readModel: c.readModel };
+      }),
     };
   }
   return map;
@@ -213,8 +216,9 @@ function runC1(domainConfigs, systemConfig) {
     'C1-002': { label: 'Listener referencia evento que ningún módulo produce', severity: 'ok', findings: [] },
     'C1-003': { label: 'Campo en listener.fields no existe en el evento del productor', severity: 'ok', findings: [] },
     'C1-004': { label: 'Campo existe pero con tipo incompatible productor/consumidor', severity: 'ok', findings: [] },
-    'C1-005': { label: 'system.yaml registra consumidor pero módulo no tiene listener declarado', severity: 'ok', findings: [] },
+    'C1-005': { label: 'system.yaml registra consumidor pero módulo no tiene listener o readModel.syncedBy declarado', severity: 'ok', findings: [] },
     'C1-006': { label: 'Listener declara producer: incorrecto', severity: 'ok', findings: [] },
+    'C1-007': { label: 'Campo de readModel no cubierto por eventos UPSERT del productor', severity: 'ok', findings: [] },
   };
 
   // C1-001: produced event in domain but zero consumers in system.yaml
@@ -277,20 +281,38 @@ function runC1(domainConfigs, systemConfig) {
     }
   }
 
-  // C1-005: system.yaml consumer present but module has no listener
+  // C1-005: system.yaml consumer present but module has no listener or readModel.syncedBy
   for (const [eventName, sysEntry] of Object.entries(systemAsyncMap)) {
-    for (const consumerModule of sysEntry.consumers) {
-      const consumerConfig = domainConfigs[consumerModule];
+    for (const consumer of sysEntry.consumers) {
+      const consumerConfig = domainConfigs[consumer.module];
       if (!consumerConfig) continue; // module domain.yaml not loaded — skip
-      const hasListener = (consumerConfig.listeners || []).some((l) => l.event === eventName);
-      if (!hasListener) {
-        checks['C1-005'].findings.push(
-          finding(
-            consumerModule,
-            `system.yaml registra '${consumerModule}' como consumidor de '${eventName}' pero el módulo no tiene listener declarado`,
-            `Evento producido por: ${sysEntry.producer}`
-          )
+
+      if (consumer.readModel) {
+        // readModel consumer → check readModels[].syncedBy[]
+        const hasSync = (consumerConfig.readModels || []).some((rm) =>
+          (rm.syncedBy || []).some((s) => s.event === eventName)
         );
+        if (!hasSync) {
+          checks['C1-005'].findings.push(
+            finding(
+              consumer.module,
+              `system.yaml registra '${consumer.module}' como consumidor readModel de '${eventName}' pero el módulo no tiene readModels[].syncedBy con ese evento`,
+              `Evento producido por: ${sysEntry.producer}, readModel esperado: ${consumer.readModel}`
+            )
+          );
+        }
+      } else {
+        // useCase consumer → check listeners[]
+        const hasListener = (consumerConfig.listeners || []).some((l) => l.event === eventName);
+        if (!hasListener) {
+          checks['C1-005'].findings.push(
+            finding(
+              consumer.module,
+              `system.yaml registra '${consumer.module}' como consumidor de '${eventName}' pero el módulo no tiene listener declarado`,
+              `Evento producido por: ${sysEntry.producer}`
+            )
+          );
+        }
       }
     }
   }
@@ -312,6 +334,35 @@ function runC1(domainConfigs, systemConfig) {
     }
   }
 
+  // C1-007: readModel field not covered by any UPSERT event from producer (RM-008)
+  for (const [moduleName, config] of Object.entries(domainConfigs)) {
+    for (const rm of config.readModels || []) {
+      // Collect field names from all UPSERT syncedBy events
+      const upsertEventFields = new Set();
+      for (const sync of rm.syncedBy || []) {
+        if ((sync.action || '').toUpperCase() !== 'UPSERT') continue;
+        const producerInfo = producedEvents[sync.event];
+        if (!producerInfo) continue; // caught by other checks
+        for (const f of producerInfo.fields) {
+          upsertEventFields.add(f.name);
+        }
+      }
+      // Check each readModel field (except 'id') is covered
+      for (const rmField of rm.fields || []) {
+        if (rmField.name === 'id') continue; // mapped to {entityName}Id in events
+        if (!upsertEventFields.has(rmField.name)) {
+          checks['C1-007'].findings.push(
+            finding(
+              moduleName,
+              `ReadModel '${rm.name}' tiene campo '${rmField.name}' que no aparece en ningún evento UPSERT de syncedBy`,
+              `Source: ${rm.source ? rm.source.module : '?'}. El campo siempre será null — agregar a los events del productor o quitar del readModel`
+            )
+          );
+        }
+      }
+    }
+  }
+
   // Assign severities
   setDefaultSeverities(checks, {
     'C1-001': 'info',
@@ -320,6 +371,7 @@ function runC1(domainConfigs, systemConfig) {
     'C1-004': 'error',
     'C1-005': 'error',
     'C1-006': 'error',
+    'C1-007': 'warning',
   });
 
   return checks;
@@ -336,6 +388,10 @@ function runC2(domainConfigs, systemConfig) {
     'C2-005': { label: 'Transición de estado sin Domain Event asociado (sin trigger)', severity: 'ok', findings: [] },
     'C2-006': { label: 'Colisión de nombre de useCase entre endpoints y listeners', severity: 'ok', findings: [] },
     'C2-007': { label: 'UseCase FindAll con nombre de agregado sin pluralizar correctamente', severity: 'ok', findings: [] },
+    'C2-008': { label: 'Evento con valor de lifecycle inválido', severity: 'ok', findings: [] },
+    'C2-009': { label: 'Evento lifecycle incompatible con configuración de entidad', severity: 'ok', findings: [] },
+    'C2-010': { label: 'Campo de lifecycle event no existe en la entidad raíz', severity: 'ok', findings: [] },
+    'C2-011': { label: 'Endpoint useCase no se resuelve a ningún agregado del módulo', severity: 'ok', findings: [] },
   };
 
   for (const [moduleName, config] of Object.entries(domainConfigs)) {
@@ -405,6 +461,7 @@ function runC2(domainConfigs, systemConfig) {
     }
 
     // C2-004: event trigger references a method that does not exist in any transition
+    // Skipped for events that use lifecycle: instead of triggers:
     const allTransitionMethods = new Set();
     for (const agg of config.aggregates || []) {
       for (const en of agg.enums || []) {
@@ -415,6 +472,7 @@ function runC2(domainConfigs, systemConfig) {
     }
     for (const agg of config.aggregates || []) {
       for (const ev of agg.events || []) {
+        if (ev.lifecycle) continue; // lifecycle events don't reference transition methods
         for (const trigger of ev.triggers || []) {
           if (!allTransitionMethods.has(trigger)) {
             checks['C2-004'].findings.push(
@@ -429,6 +487,74 @@ function runC2(domainConfigs, systemConfig) {
       }
     }
 
+    // C2-008: event lifecycle value is not one of the valid options
+    const validLifecycleValues = ['create', 'update', 'delete', 'softDelete'];
+    for (const agg of config.aggregates || []) {
+      for (const ev of agg.events || []) {
+        if (ev.lifecycle && !validLifecycleValues.includes(ev.lifecycle)) {
+          checks['C2-008'].findings.push(
+            finding(
+              moduleName,
+              `Evento '${ev.name}' tiene lifecycle: '${ev.lifecycle}' que no es un valor válido`,
+              `Valores válidos: ${validLifecycleValues.join(', ')}`
+            )
+          );
+        }
+      }
+    }
+
+    // C2-009: lifecycle value is incompatible with entity configuration
+    for (const agg of config.aggregates || []) {
+      const rootEntity = (agg.entities || []).find(e => e.isRoot);
+      const hasSoftDelete = rootEntity && rootEntity.hasSoftDelete;
+      for (const ev of agg.events || []) {
+        if (ev.lifecycle === 'softDelete' && !hasSoftDelete) {
+          checks['C2-009'].findings.push(
+            finding(
+              moduleName,
+              `Evento '${ev.name}' tiene lifecycle: 'softDelete' pero la entidad raíz '${rootEntity ? rootEntity.name : agg.name}' no tiene hasSoftDelete: true`,
+              `Agregado: ${agg.name}. Agregar hasSoftDelete: true a la entidad raíz o cambiar lifecycle a 'delete'`
+            )
+          );
+        }
+        if (ev.lifecycle === 'delete' && hasSoftDelete) {
+          checks['C2-009'].findings.push(
+            finding(
+              moduleName,
+              `Evento '${ev.name}' tiene lifecycle: 'delete' pero la entidad raíz '${rootEntity.name}' tiene hasSoftDelete: true`,
+              `Agregado: ${agg.name}. Usar lifecycle: 'softDelete' en su lugar o quitar hasSoftDelete`
+            )
+          );
+        }
+      }
+    }
+
+    // C2-010: lifecycle event field not found in root entity
+    for (const agg of config.aggregates || []) {
+      const rootEntityC10 = (agg.entities || []).find(e => e.isRoot);
+      if (!rootEntityC10) continue;
+      const entityFieldNames = new Set((rootEntityC10.fields || []).map(f => f.name));
+      const entityBase = rootEntityC10.name.charAt(0).toLowerCase() + rootEntityC10.name.slice(1);
+      for (const ev of agg.events || []) {
+        if (!ev.lifecycle) continue;
+        for (const ef of ev.fields || []) {
+          // Skip {entityName}Id — mapped to aggregateId in DomainEvent
+          if (ef.name === entityBase + 'Id') continue;
+          // Skip temporal auto-resolved fields (*At + LocalDateTime)
+          if (ef.name.endsWith('At') && ef.type === 'LocalDateTime') continue;
+          if (!entityFieldNames.has(ef.name)) {
+            checks['C2-010'].findings.push(
+              finding(
+                moduleName,
+                `Evento '${ev.name}' (lifecycle: ${ev.lifecycle}) tiene campo '${ef.name}' que no existe en la entidad raíz '${rootEntityC10.name}'`,
+                `Agregado: ${agg.name}. Quitar '${ef.name}' del evento o agregar el campo a la entidad`
+              )
+            );
+          }
+        }
+      }
+    }
+
     // C2-005: transition method without any associated domain event trigger
     for (const agg of config.aggregates || []) {
       for (const en of agg.enums || []) {
@@ -566,6 +692,92 @@ function runC2(domainConfigs, systemConfig) {
         }
       }
     }
+
+    // C2-011: Endpoint useCase not semantically resolvable to any aggregate
+    // Detects FindAll/Get use cases that won't match any aggregate via exact
+    // or fuzzy matching — these silently fall to scaffold with the wrong
+    // aggregate's ResponseDto, producing code that doesn't compile.
+    const allAggs = config.aggregates || [];
+    for (const ver of (config.endpoints && config.endpoints.versions) || []) {
+      for (const op of ver.operations || []) {
+        const uc = op.useCase || '';
+        let resolved = false;
+
+        for (const agg of allAggs) {
+          const aggName = agg.name;
+          const aggPlural = pluralizeWord(aggName);
+          // Exact standard match
+          if (uc === `Create${aggName}` || uc === `Update${aggName}` ||
+              uc === `Delete${aggName}` || uc === `Get${aggName}` ||
+              uc === `FindAll${aggPlural}`) {
+            resolved = true;
+            break;
+          }
+          // Fuzzy FindAll: singular of suffix is prefix of aggregate name (or vice-versa)
+          if (uc.startsWith('FindAll')) {
+            const suffix = uc.slice(7);
+            if (suffix) {
+              const singular = singularizeWord(suffix).toLowerCase();
+              const aggLower = aggName.toLowerCase();
+              if (aggLower.startsWith(singular) || singular.startsWith(aggLower)) {
+                resolved = true;
+                break;
+              }
+            }
+          }
+          // Fuzzy Get: suffix is prefix of aggregate name (or vice-versa)
+          if (uc.startsWith('Get') && !uc.startsWith('GetAll')) {
+            const suffix = uc.slice(3);
+            if (suffix) {
+              const suffixLower = suffix.toLowerCase();
+              const aggLower = aggName.toLowerCase();
+              if (aggLower.startsWith(suffixLower) || suffixLower.startsWith(aggLower)) {
+                resolved = true;
+                break;
+              }
+            }
+          }
+          // Transition match
+          const entities = agg.entities || [];
+          const rootEntity = entities.find(e => e.isRoot) || entities[0] || {};
+          const enums = rootEntity.enums || agg.enums || [];
+          for (const enumDef of enums) {
+            for (const tr of (enumDef.transitions || [])) {
+              const methodPascal = tr.method.charAt(0).toUpperCase() + tr.method.slice(1);
+              if (uc === `${methodPascal}${aggName}`) {
+                resolved = true;
+              }
+            }
+          }
+          if (resolved) break;
+          // SubEntity match
+          const rels = (rootEntity.relationships || []).filter(r => r.type === 'OneToMany' && !r.isInverse);
+          for (const rel of rels) {
+            if (uc === `Add${rel.target}` || uc === `Remove${rel.target}`) {
+              resolved = true;
+              break;
+            }
+          }
+          if (resolved) break;
+          // Substring fallback: aggregate name inside useCase
+          if (uc.toLowerCase().includes(aggName.toLowerCase())) {
+            resolved = true;
+            break;
+          }
+        }
+
+        if (!resolved) {
+          const firstAgg = allAggs.length > 0 ? allAggs[0].name : '(none)';
+          checks['C2-011'].findings.push(
+            finding(
+              moduleName,
+              `UseCase '${uc}' no se resuelve a ningún agregado del módulo — se asignará al primero ('${firstAgg}') y generará código con tipos incorrectos`,
+              `Versión: ${ver.version}. Considere renombrar el useCase para que contenga el nombre del agregado, o verificar que el agregado destino existe.`
+            )
+          );
+        }
+      }
+    }
   }
 
   setDefaultSeverities(checks, {
@@ -576,6 +788,10 @@ function runC2(domainConfigs, systemConfig) {
     'C2-005': 'info',
     'C2-006': 'error',
     'C2-007': 'error',
+    'C2-008': 'error',
+    'C2-009': 'warning',
+    'C2-010': 'error',
+    'C2-011': 'error',
   });
 
   return checks;

package/src/utils/naming.js

@@ -56,6 +56,15 @@ function pluralizeWord(word) {
   return pluralize(word);
 }
 
+/**
+ * Singularize a word
+ * @param {string} word - Word to singularize
+ * @returns {string} Singularized word
+ */
+function singularizeWord(word) {
+  return pluralize.singular(word);
+}
+
 /**
  * Convert package name to path
  * @param {string} packageName - Package name (e.g., com.company.project)
@@ -129,6 +138,7 @@ module.exports = {
   toSnakeCase,
   toKebabCase,
   pluralizeWord,
+  singularizeWord,
   toPackagePath,
   getBaseEntity,
   artifactIdToPackageName,

package/src/utils/validator.js

@@ -1,5 +1,6 @@
 const fs = require('fs-extra');
 const path = require('path');
+const { toCamelCase } = require('./naming');
 
 /**
  * Validate project name
@@ -107,7 +108,8 @@ async function isEva4jProject(dir) {
  * @returns {boolean} True if module exists
  */
 async function moduleExists(projectDir, packagePath, moduleName) {
-  const modulePath = path.join(projectDir, 'src', 'main', 'java', packagePath, moduleName);
+  const normalized = toCamelCase(moduleName);
+  const modulePath = path.join(projectDir, 'src', 'main', 'java', packagePath, normalized);
   return await fs.pathExists(modulePath);
 }
 

package/src/utils/yaml-to-entity.js

@@ -49,12 +49,16 @@ async function parseDomainYaml(yamlPath, packageName = '', moduleName = '') {
     );
   }
 
+  const ports = parsePorts(domainData, moduleName);
+  const readModels = parseReadModels(domainData, moduleName, ports);
+
   return {
     aggregates,
     allEnums: extractAllEnums(domainData.aggregates),
     endpoints,
     listeners,
-    ports: parsePorts(domainData, moduleName)
+    ports,
+    readModels
   };
 }
 
@@ -108,7 +112,8 @@ function parseAggregate(aggregateData) {
       name: eventName,
       fieldName: toCamelCase(eventName),
       fields: eventFields,
-      triggers: event.triggers || []
+      triggers: event.triggers || [],
+      lifecycle: event.lifecycle || null
     };
   });
 
@@ -122,6 +127,17 @@ function parseAggregate(aggregateData) {
     });
   });
 
+  // Build lifecycle map: { create → [event, ...], update → [...], delete → [...], softDelete → [...] }
+  // Used by templates to emit raise() calls at CRUD lifecycle points.
+  const VALID_LIFECYCLE_VALUES = ['create', 'update', 'delete', 'softDelete'];
+  const lifecycleEventsMap = {};
+  domainEvents.forEach(event => {
+    if (event.lifecycle && VALID_LIFECYCLE_VALUES.includes(event.lifecycle)) {
+      if (!lifecycleEventsMap[event.lifecycle]) lifecycleEventsMap[event.lifecycle] = [];
+      lifecycleEventsMap[event.lifecycle].push(event);
+    }
+  });
+
   return {
     name: toPascalCase(name),
     packageName: aggregateData.package || '',
@@ -132,6 +148,7 @@ function parseAggregate(aggregateData) {
     allEntities: parsedEntities,
     domainEvents,
     triggeredEventsMap,
+    lifecycleEventsMap,
     enums: aggregateEnums
   };
 }
@@ -1253,6 +1270,255 @@ function parsePorts(domainData, moduleName = '') {
   });
 }
 
+/**
+ * Derive a Kafka topic name from an event class name.
+ * Strips trailing 'Event' suffix, then converts to SCREAMING_SNAKE_CASE.
+ * e.g. 'ProductCreatedEvent' → 'PRODUCT_CREATED'
+ *      'OrderCancelled'      → 'ORDER_CANCELLED'
+ * @param {string} eventName - PascalCase event name
+ * @returns {string} SCREAMING_SNAKE_CASE topic name
+ */
+function deriveTopicFromEventName(eventName) {
+  const base = eventName.endsWith('Event') ? eventName.slice(0, -5) : eventName;
+  // PascalCase → SCREAMING_SNAKE_CASE
+  return base
+    .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+    .replace(/([A-Z])([A-Z][a-z])/g, '$1_$2')
+    .toUpperCase();
+}
+
+/**
+ * Parse the optional readModels section from domain.yaml.
+ * Declares local read model projections maintained via domain events
+ * from external bounded contexts.
+ * @param {Object} domainData - Raw parsed YAML data
+ * @param {string} moduleName - Current module name
+ * @param {Array} ports - Parsed ports (for RM-009 warning)
+ * @returns {Array} Parsed read models array (empty if not declared)
+ */
+function parseReadModels(domainData, moduleName = '', ports = []) {
+  if (!domainData.readModels || !Array.isArray(domainData.readModels)) return [];
+
+  const validActions = ['UPSERT', 'DELETE', 'SOFT_DELETE'];
+
+  return domainData.readModels.map(rm => {
+    const name = toPascalCase(rm.name);
+
+    // RM-001: name must end with 'ReadModel'
+    if (!name.endsWith('ReadModel')) {
+      throw new Error(
+        `[RM-001] Read model "${name}": name must end with "ReadModel" suffix. ` +
+        `Rename to "${name}ReadModel".`
+      );
+    }
+
+    // RM-002: tableName must start with 'rm_'
+    if (!rm.tableName || !rm.tableName.startsWith('rm_')) {
+      throw new Error(
+        `[RM-002] Read model "${name}": tableName must start with "rm_" prefix. ` +
+        `Got: "${rm.tableName || '(empty)'}".`
+      );
+    }
+
+    // Source is required
+    if (!rm.source || !rm.source.module || !rm.source.aggregate) {
+      throw new Error(
+        `[RM-010] Read model "${name}": source.module and source.aggregate are required.`
+      );
+    }
+
+    // RM-010: source.module must differ from current module
+    if (rm.source.module === moduleName || toKebabCase(rm.source.module) === toKebabCase(moduleName)) {
+      throw new Error(
+        `[RM-010] Read model "${name}": source.module ("${rm.source.module}") is the same as the current module. ` +
+        `Read models are for cross-module projections only.`
+      );
+    }
+
+    // Parse fields
+    const fields = (rm.fields || []).map(f => ({
+      name: toCamelCase(f.name),
+      javaType: f.type
+    }));
+
+    // RM-004: fields must include an 'id' field
+    if (!fields.some(f => f.name === 'id')) {
+      throw new Error(
+        `[RM-004] Read model "${name}": fields must include an "id" field.`
+      );
+    }
+
+    // Parse syncedBy
+    const syncedBy = rm.syncedBy || [];
+
+    // RM-005: syncedBy must have at least one entry
+    if (syncedBy.length === 0) {
+      throw new Error(
+        `[RM-005] Read model "${name}": syncedBy must have at least one entry.`
+      );
+    }
+
+    // Derive the source aggregate's id key for payload extraction
+    // e.g., source.aggregate = 'Product' → sourceIdKey = 'productId'
+    const sourceBase = rm.source.aggregate.charAt(0).toLowerCase() + rm.source.aggregate.slice(1);
+    const sourceIdKey = sourceBase + 'Id';
+
+    const parsedSyncedBy = syncedBy.map(sync => {
+      const eventName = toPascalCase(sync.event);
+      const action = (sync.action || '').toUpperCase();
+
+      // RM-006: action must be valid
+      if (!validActions.includes(action)) {
+        throw new Error(
+          `[RM-006] Read model "${name}", event "${eventName}": ` +
+          `syncedBy action must be one of ${validActions.join(', ')}. Got: "${action}".`
+        );
+      }
+
+      const baseName = eventName.endsWith('Event') ? eventName.slice(0, -5) : eventName;
+      const topic = sync.topic || deriveTopicFromEventName(eventName);
+      const topicKey = topic.toLowerCase().replace(/_/g, '-');
+
+      return {
+        event: eventName,
+        eventBaseName: baseName,
+        action,
+        integrationEventClassName: `${baseName}IntegrationEvent`,
+        listenerClassName: `${baseName}ReadModelListener`,
+        topicConstant: topic,
+        topicKey,
+        topicSpringProperty: `\${topics.${topicKey}}`,
+        topicVariableName: toCamelCase(topicKey.replace(/-/g, '_')),
+        // UPSERT needs all readModel fields; DELETE/SOFT_DELETE only need the id
+        // payloadKey maps readModel field names to producer payload keys
+        // e.g., readModel 'id' → payload 'productId' (convention {entityName}Id)
+        fields: action === 'UPSERT'
+          ? fields.map(f => ({ ...f, payloadKey: f.name === 'id' ? sourceIdKey : f.name }))
+          : [{ name: 'id', javaType: 'String', payloadKey: sourceIdKey }]
+      };
+    });
+
+    const hasSoftDelete = parsedSyncedBy.some(s => s.action === 'SOFT_DELETE');
+    const sourceName = toPascalCase(rm.source.aggregate);
+    const sourceModule = rm.source.module;
+
+    // RM-009: warn if ports still has sync calls to the same source module
+    const conflictingPorts = ports.filter(p =>
+      p.target && (p.target === sourceModule || toKebabCase(p.target) === toKebabCase(sourceModule))
+    );
+    if (conflictingPorts.length > 0) {
+      const serviceNames = conflictingPorts.map(p => p.serviceName).join(', ');
+      console.warn(
+        `⚠️  [RM-009] Read model "${name}": ports: section still contains sync calls ` +
+        `to module "${sourceModule}" (services: ${serviceNames}). Consider removing them ` +
+        `since the read model provides local access to that data.`
+      );
+    }
+
+    return {
+      name,
+      sourceName,
+      sourceModule,
+      tableName: rm.tableName,
+      fields,
+      syncedBy: parsedSyncedBy,
+      hasSoftDelete,
+      // Derived class names
+      domainClassName: name,
+      jpaEntityName: `${name}Jpa`,
+      jpaRepositoryName: `${name}JpaRepository`,
+      repositoryName: `${name}Repository`,
+      repositoryImplName: `${name}RepositoryImpl`,
+      syncHandlerName: `Sync${sourceName}ReadModelHandler`
+    };
+  });
+}
+
+/**
+ * Resolve event constructor arguments for a domain event given entity context.
+ * Replicates the same resolution logic used in AggregateRoot.java.ejs for transitions.
+ *
+ * @param {Object} event - Parsed domain event { name, fields }
+ * @param {string} entityName - PascalCase aggregate root name (e.g. 'Product')
+ * @param {Array}  entityFields - Parsed fields of the root entity
+ * @param {Array}  valueObjects - Parsed value objects of the aggregate
+ * @param {string} prefix - Expression prefix for getters (e.g. 'this' or 'updated' or 'entity')
+ * @returns {Object} { args: string[], needsLocalDateTime: boolean, needsUUID: boolean }
+ */
+function resolveEventArgs(event, entityName, entityFields, valueObjects = [], prefix = 'this') {
+  const entityBase = entityName.charAt(0).toLowerCase() + entityName.slice(1);
+  const args = [`${prefix}.getId()`];
+  let needsLocalDateTime = false;
+  let needsUUID = false;
+
+  (event.fields || []).forEach(ef => {
+    // Skip {entityName}Id — already provided as aggregateId in the DomainEvent constructor
+    if (ef.name === entityBase + 'Id') return;
+
+    const matched = entityFields.find(f => f.name === ef.name);
+    if (matched) {
+      if (matched.javaType === ef.javaType) {
+        const cap = ef.name.charAt(0).toUpperCase() + ef.name.slice(1);
+        args.push(`${prefix}.get${cap}()`);
+        return;
+      }
+      // Type mismatch: entity field may be a VO wrapping the expected primitive/type
+      const vo = (valueObjects || []).find(v => v.name === matched.javaType);
+      if (vo) {
+        const voSub = vo.fields.find(voF => voF.name === ef.name && voF.javaType === ef.javaType)
+                    || vo.fields.find(voF => voF.javaType === ef.javaType);
+        if (voSub) {
+          const oCap = ef.name.charAt(0).toUpperCase() + ef.name.slice(1);
+          const sCap = voSub.name.charAt(0).toUpperCase() + voSub.name.slice(1);
+          args.push(`${prefix}.get${oCap}().get${sCap}()`);
+          return;
+        }
+      }
+      // Enum → String: convert via .name()
+      if (matched.isEnum && ef.javaType === 'String') {
+        const cap = ef.name.charAt(0).toUpperCase() + ef.name.slice(1);
+        args.push(`${prefix}.get${cap}().name()`);
+        return;
+      }
+      args.push(`null /* TODO: provide ${ef.name} (entity returns ${matched.javaType}, expected ${ef.javaType}) */`);
+      return;
+    }
+    if (ef.name.endsWith('At') && ef.javaType === 'LocalDateTime') {
+      args.push('LocalDateTime.now()');
+      needsLocalDateTime = true;
+      return;
+    }
+    args.push(`null /* TODO: provide ${ef.name} */`);
+  });
+
+  return { args, needsLocalDateTime, needsUUID };
+}
+
+/**
+ * Pre-compute resolved arguments for all lifecycle events.
+ * Returns an enriched lifecycleEventsMap where each event has a `resolvedArgs` array.
+ *
+ * @param {Object} lifecycleEventsMap - { create: [event, ...], update: [...], ... }
+ * @param {string} entityName - PascalCase aggregate root name
+ * @param {Array}  entityFields - Parsed fields of the root entity
+ * @param {Array}  valueObjects - Parsed value objects of the aggregate
+ * @returns {Object} enriched map: { create: [{ ...event, resolvedArgs, needsLocalDateTime }], ... }
+ */
+function resolveLifecycleEventArgs(lifecycleEventsMap, entityName, entityFields, valueObjects = []) {
+  const resolved = {};
+  // Each lifecycle type uses a different variable name in the generated code
+  // update uses 'this' because raise() is now inside the entity's update() method
+  const prefixMap = { create: 'this', update: 'this', delete: 'entity', softDelete: 'this' };
+  for (const [lifecycle, events] of Object.entries(lifecycleEventsMap)) {
+    const prefix = prefixMap[lifecycle] || 'this';
+    resolved[lifecycle] = events.map(event => {
+      const { args, needsLocalDateTime } = resolveEventArgs(event, entityName, entityFields, valueObjects, prefix);
+      return { ...event, resolvedArgs: args, needsLocalDateTime };
+    });
+  }
+  return resolved;
+}
+
 module.exports = {
   parseDomainYaml,
   parseAggregate,
@@ -1263,5 +1529,8 @@ module.exports = {
   generateValidationImports,
   generateAggregateMethodImports,
   parseListeners,
-  parsePorts
+  parsePorts,
+  parseReadModels,
+  resolveEventArgs,
+  resolveLifecycleEventArgs
 };