ADR 002 — Renomeação Mediator/ → Cqrs/

Status: Accepted Data: 2026-05-01 Versão alvo: 2.0.1

Contexto

A versão 2.0.0 do DevPack (Fase 0) substituiu MediatR por Mediator (martinothamar) como infraestrutura de mediator interna. As abstrações de CQRS do DevPack (ICommand, IQuery, ICommandHandler, etc.) ficaram no namespace ITLab.Template.DevPack.Mediator, mantendo o nome herdado da era MediatR.

Após a release, identificou-se uma fricção real:

• A biblioteca Mediator (martinothamar) declara seus tipos no namespace raiz Mediator — Mediator.IMediator, Mediator.IPublisher, Mediator.ICommand, Mediator.IQuery, Mediator.INotification.
• Nosso namespace ITLab.Template.DevPack.Mediator reexpõe ICommand, IQuery, INotificationEvent — todos com nomes que colidem ou aproximam-se dos da biblioteca raiz.
• Quando um arquivo do consumidor precisa importar ambos (raro, mas não nulo — ex.: um arquivo que define um command e também injeta Mediator.IMediator), o IntelliSense mostra dois ICommand/IQuery, gerando ambiguidade.
• O atrito é particularmente ruim para agentes de IA, que dependem de previsibilidade lexical para gerar código correto.

Decisão

Renomear o namespace ITLab.Template.DevPack.Mediator para ITLab.Template.DevPack.Cqrs. Mover a pasta src/.../Mediator/ para src/.../Cqrs/. Nenhum tipo público teve nome alterado.

Alternativas consideradas

Manter o nome Mediator/

Custo zero, mas a colisão permanece. Descartada porque a motivação principal era resolver justamente isso.

Renomear para Messaging/

Nome semanticamente atraente (cobre commands, queries e notifications), mas conflitou com pasta existente: src/ITLab.Template.DevPack/Messaging/ já existe e contém abstrações de broker integration (EMessageDisposition, MessageHandlingResult, MessagingErrors) — vocabulário consolidado que descreve message settlement em filas (Service Bus). Forçar o nome Messaging/ para CQRS in-process exigiria renomear a pasta antiga ou misturar dois conceitos distintos sob o mesmo guarda-chuva. Custo alto sem ganho proporcional.

Renomear para Cqrs/

Adotada. O termo é específico, idiomático no ecossistema .NET, e não colide com nenhuma outra área do DevPack nem com a biblioteca raiz Mediator. A limitação semântica de "CQRS" excluir notifications no sentido estrito é absorvida — INotificationEvent no DevPack é uso minoritário e cabe no namespace sem fricção prática.

Renomear para Mediation/

Considerada como compromisso entre preservar o conceito de "mediator pattern" e evitar colisão exata. Descartada por ser termo menos comum no idioma .NET e não trazer ganho claro sobre Cqrs/.

Renomear para Dispatching/

Considerada por capturar "in-process dispatch" abrangentemente. Descartada por soar implementacional demais e ser pouco usada no ecossistema.

Consequências

• Versão 2.0.1 publicada como patch (DevPack ainda não tem consumidores externos — WorkGuardian usa cópias internas, template ainda não foi construído). Critério "breaking change" pressupõe consumidores que precisam migrar; não é o caso. Patch reflete a essência: correção rápida de uma decisão pré-release que poderia ter sido melhor tomada na Fase 0.
• Migração para consumidores futuros: substituir using ITLab.Template.DevPack.Mediator; por using ITLab.Template.DevPack.Cqrs;. Nenhuma mudança em assinaturas, retorno, comportamento ou dependências.
• Messaging/ mantém-se intocada com sua finalidade original (broker integration). O Cqrs/README.md documenta explicitamente a separação entre as duas áreas para evitar confusão futura.
• Coabitação limpa: após a renomeação, um arquivo do consumidor pode importar using Mediator; e using ITLab.Template.DevPack.Cqrs; simultaneamente sem ambiguidade — os dois namespaces não compartilham nomes de tipos.

Observação operacional

A renomeação foi executada após uma tentativa intermediária de mover para Messaging/, que revelou o conflito acima. Durante a reversão, o Messaging/README.md original foi sobrescrito e teve que ser reconstruído a partir do conteúdo dos .cs da área e do inventário do DevPack. O conteúdo recriado segue o padrão das outras áreas e está validado contra o build.