Eventos e Outbox

Esta página especifica um contrato futuro. O Nexio consome Gryd 5.0.2; o checkout de Gryd.IO develop inspecionado em a4e8260 não contém o outbox aqui descrito. A estrutura do Nexio em 23eedd8 contém pontos de composição e testes de arquitetura; não implementa esse ciclo. Wolverine continua adiado.

1. Efeito obrigatório é chamada explícita na transação produtora.
2. Evento em memória só sai após o commit da transação que o produziu.
3. Reação que não pode desaparecer nasce como mensagem durável junto do fato.
4. Plataforma fornece mecanismo; produtor possui tabela e migração; negócio possui significado.
5. Entrega é ao menos uma vez, com idempotência atômica no consumidor.
6. Ordem é por agregado, preservando a primeira mensagem ainda não concluída.
7. Claims são curtos, com lease e recuperação; I/O externo fica fora da transação de claim.
8. Implementação e migração precedem adoção; resultado de spike não comprova prontidão operacional.

Boa parte deste épico é composição, não construção — e uma parte é remoção. O framework já tem o vocabulário de evento, o motor de jobs com DLQ e a trilha de auditoria; o que falta é o fio que liga os três no momento certo.

O GrydAuthDbContext sobrescreve SaveChangesAsync e roda um laço: salva, publica os eventos dos agregados rastreados, verifica se algum handler deixou mudança pendente e, se deixou, salva de novo — até dez rodadas. Tudo isso dentro da transação que ele mesmo abriu, e só ele: o GrydFilesDbContext é DbContext puro e não despacha evento nenhum.

As três falhas da carta, respondidas

O registro do outbox é mapeado pelo DbContext do produtor. O worker enumera fontes explicitamente registradas, com cursor e limite por fonte/tenant. Consumidor local que precise de durabilidade usa o mesmo mecanismo; estar no mesmo processo não torna um callback durável.

Registro mínimo da coleta: (dbContextInstanceId, transactionId, savepointGeneration, eventId). Dois DbContexts numa requisição podem confirmar ou reverter separadamente: commit de A nunca publica eventos pendentes de B. Múltiplos SaveChanges na mesma transação acumulam somente eventos daquela transação.

A API concreta dos interceptors será validada por testes de integração antes da publicação do pacote; esta tabela é o contrato, não código executável. ExecuteInTransactionAsync deve respeitar transação ambiente compartilhada e não confirmar um escopo interno prematuramente. Eventos não substituem coordenação atômica entre contextos.

InboxMessage pertence ao consumidor e tem chave única (tenantId, consumerName, messageId), payloadHash e resultado. Insert de dedupe e efeito compartilham transação. Mesma chave com payload distinto é conflito. Efeito externo exige chave estável aceita pelo destino ou consulta/reconciliação; inbox isolado não cria exactly-once na rede.

Uma candidata só é cabeça quando não existe mensagem de sequência menor do mesmo agregado com status diferente de Dispatched. O bloqueador inclui Failed em backoff, Dispatching com lease vivo e DeadLettered. Filtrar apenas mensagens prontas e depois ordenar não cumpre essa condição.

-- Predicado da cabeça; pseudocódigo SQL a validar no provedor
NOT EXISTS (
  SELECT 1 FROM producer_outbox earlier
  WHERE earlier.tenant_id = candidate.tenant_id
    AND earlier.aggregate_key = candidate.aggregate_key
    AND earlier.aggregate_sequence < candidate.aggregate_sequence
    AND earlier.status <> 'Dispatched'
)
-- Só depois: elegibilidade por estado, nextAttemptAt e lease.
-- Claim sob trava curta; commit; envio fora da transação.

SKIP LOCKED auxilia claims concorrentes, mas não garante ordem sozinho. A raiz serializa geração/commit de sequências; claim por agregado evita duas cabeças em paralelo. Lease renovável reduz sobreposição, mas queda de rede ainda pode repetir envio tardio. Consumidor que exige ordem guarda última sequência e dedupe no mesmo commit, retendo mensagens futuras até preencher lacunas; transporte preserva chave de ordenação quando disponível.

Justiça entre tenants é aplicada na seleção SQL/round-robin de cursores antes do LIMIT global. Cortar quotas em memória depois do LIMIT pode deixar um tenant pequeno sem atendimento. Começar sem particionamento fixo; medir backlog, latência e contenção antes de introduzir partições.

A enumeração de fontes é operação técnica privilegiada, limitada às fontes registradas. Cada mensagem abre novo escopo, restaura tenant, empresa, correlação e credencial de serviço autorizada, executa, e limpa o contexto em finally. Nenhum AsyncLocal, sessão de banco ou cache pode vazar para a mensagem seguinte. Valor enviado no payload não concede acesso por si.

Workers usam UserCompanyRole ou concessão equivalente de serviço, com operações explícitas. Testar sequência A → B → falha → A, concorrência, tenant ausente, revogação e retorno de conexão ao pool. Consulta de estado não pode usar IgnoreQueryFilters como atalho irrestrito.

O GrydAuth inspecionado publica eventos em override de SaveChanges; não se deve inferir que já oferece o contrato após commit. Antes de migrar, classificar todos os handlers em atômicos, duráveis e best effort; transformar efeitos obrigatórios em chamadas explícitas e criar outbox durável no produtor.

Publicar versão da plataforma com testes de transações explícitas, implícitas, múltiplos saves/contextos, savepoints e falhas. Migrar produtores e consumidores com compatibilidade de payload, definir corte de backlog e só então remover o despacho anterior. Não habilitar em produção dois caminhos que repitam o mesmo efeito. O Nexio só adota após consumir e validar a versão publicada.

Último voto: serializar ApprovalRequest e verificar expectedVersion; validar usuário e revisão; gravar voto; chamar o contrato do processo; reavaliar todos os limites orçamentários sob trava. Sucesso aplica estado e lançamentos. Insuficiência esperada devolve ReturnedForBudget, persiste Returned com motivo e aviso no outbox, sem novo compromisso. Exceção técnica reverte a operação completa.

Pedido efetivo: gravar versão efetiva, delta de obrigação e mensagem de integração na mesma transação. O worker envia exatamente a revisão persistida. ACK de transporte e status Received/Applied do ERP são fatos separados, reconciliáveis pela identidade estável da operação.

O AuditLog responde bem a "que campo mudou". Não responde a "quem autorizou". São perguntas diferentes e o ChangeType — Created, Updated, Deleted, Accessed — só sabe a primeira.

Convenção do vocabulário

{modulo}.{agregado}.{verbo-no-passado}      // minúsculo, pontos, ≤ 80 caracteres

nexio.approval.granted
nexio.approval.revoked
nexio.bank-account.authorized
gryd-files.download-url.issued
gryd-messaging.outbox.retried
gryd-auth.user.impersonated

O verbo no passado não é estética: a trilha registra o que aconteceu, e grant descreveria uma intenção que ainda pode falhar. Um teste de convenção varre as constantes de cada módulo e quebra o build em nome fora do padrão — é o mesmo tipo de guarda que o GrydFiles usa contra chave desconhecida no appsettings.

Superfície

// Gryd.Observability.Audit
AuditEntry.Builder("ApprovalRequest", id)
    .WithChangeType(EntityChangeType.Updated)
    .WithAction(NexioAuditActions.ApprovalGranted)     // ← novo
    .WithUser(approverId)
    .WithMetadata("Quorum", "2/3")
    .Build();

// consulta
GET /api/v1/audit-logs?action=nexio.approval.granted&from=2026-09-01

Migração: coluna anulável, índice e um UPDATE que promove additional_data->>'Event' para action nas linhas já escritas pelo GrydFiles, prefixando o módulo. Depois disso o FileAuditTrail troca quatro WithMetadata("Event", …) por quatro WithAction(…) e a duplicação some — que é o teste real de que a coluna era mesmo a peça faltante.

Este pedido chegou como pendência e já está resolvido no código — o que não existe é o contrato escrito. A carta do Nexio diz que o mapeador reconhece nove sufixos; nesta branch reconhece dez.

A regra, publicada

// Gryd.API — o mapeador deixa de citar módulo
public interface IErrorCodeStatusMapper
{
    int Resolve(string errorCode);   // exato → sufixo → 400
}

// GrydAuth, na sua própria composição:
services.MapErrorCode("USER_EMAIL_UNAVAILABLE", StatusCodes.Status409Conflict,
    because: "anti-disclosure: não revelar se o e-mail existe");

// Nexio, se algum dia precisar:
services.MapErrorCode("BUDGET_PERIOD_CLOSED", StatusCodes.Status423Locked);

O parâmetro because não é decoração: ele aparece no relatório de mapeamentos que o startup imprime em desenvolvimento e na documentação de erros do Swagger. Uma exceção à convenção sem motivo escrito vira, em dois anos, uma linha que ninguém ousa remover.

Medir idade da cabeça pendente, backlog por produtor/tenant, tentativas, leases expirados, dead letters, falhas de dedupe e tempo até aplicação no destino. Alertas não dependem exclusivamente do mesmo canal de notificação que estão monitorando. Health distingue disponibilidade da API de atraso da integração.

Operação exige inspeção segura do payload, retry com mesma identidade, correção versionada quando o conteúdo estiver errado, e reconciliação antes de descartar. Retenção do inbox cobre ao menos a janela máxima de retry/restauração do produtor; expurgo não pode permitir repetição de efeitos financeiros antigos.

Backup/restauração deve manter fato, outbox, inbox e referências de arquivo consistentes. Após restore, reconciliar operações já aplicadas fora do banco e invalidar sessões/permissões restauradas. Definir RPO/RTO, executar restauração ensaiada e medir resultados antes do primeiro cliente. Não há garantia operacional comprovada pelos testes de estrutura atuais.

Nenhuma permissão nova para evento de domínio: reação em processo não tem superfície. E nenhuma permissão de escrita no outbox — a única forma de uma mensagem nascer é um efeito de negócio gravado numa transação. Um POST que criasse mensagem seria um caminho para forjar um fato que nunca aconteceu.

Configurar por fonte: intervalo de varredura, batchSize, quota por tenant, timeout de transporte, leaseDuration/renewal, backoff, maxAttempts e retenção de Dispatched/inbox. Validar lease contra timeout e margem de renovação. Não impor 32 partições ou lock que permaneça aberto durante chamada de rede.

Wake-up em memória é apenas otimização no mesmo processo. API e Worker separados dependem da varredura ou sinal durável; declarar e medir a latência máxima esperada. Limites de quota e alertas devem impedir que um tenant monopolize o worker.

• Tempo relativo de commit e evento em transação explícita/implícita; duas transações/DbContexts na mesma requisição; múltiplos saves; rollback de savepoint; cancelamento; commit incerto.
• Atomicidade de efeito e outbox, e de inbox e efeito; mesmo ID com conteúdo diferente; queda após envio e antes do ACK persistido.
• Mensagem anterior em backoff, Dispatching ou DeadLettered impede a posterior; queda recupera lease; worker antigo não confirma lease substituído.
• Concorrência e equidade entre tenants; contexto limpo após falha; revogação de credencial; restore com dedupe ainda válido.
• Último voto sem verba preservado em Returned; nenhuma transição Approved ou entrada de consumo adicional.

São requisitos de validação da implementação futura. Os testes atuais do Nexio não executam estes cenários de banco ou mensageria.

Construir só é decisão se as alternativas foram olhadas. O outbox transacional é um padrão maduro com implementações prontas em .NET, e esta seção existe para que a escolha de escrever fique registrada como escolha, não como omissão. O despacho pós-commit é outro caso: ninguém vende essa peça isolada — todas as bibliotecas a entregam embutida num message bus.

O padrão que decide

As três coisas que nenhuma delas faz

O que se adota de mercado desde o primeiro dia

A resposta a "não reinventar a roda" não é adotar um bus: é não escrever as quatro peças que já são padrão. Nenhuma delas acopla arquitetura — são formato, matemática e convenção.

Wolverine · o candidato que merece spike

É a única opção que resolve as duas camadas deste documento sem exigir broker: o outbox EF Core é nativo, as filas locais podem ser duráveis em PostgreSQL, e os handlers rodam a partir da fila — ou seja, depois do commit. De quebra, resolveria o congelamento do MediatR descrito abaixo. Descartá-lo por reflexo seria desonesto.

Critério de saída do spike · 2 a 3 dias, em branch

• Os quatro behaviors do MediatR cabem no pipeline do Wolverine sem gambiarra — em especial o TenantScopeBehavior, que hoje depende da ordem do pipeline.
• O TenantContextAccessor é restaurado na execução da fila durável, e uma mensagem de um tenant não enxerga dado de outro.
• O AggregateRoot atual é raspável pela API de scraping sem mudar as 74 chamadas a AddDomainEvent.
• O GrydJobs continua dono do agendamento, ou o Wolverine o substitui sem perder dashboard, DLQ e política de retry por tipo.
• O impacto no consumidor do framework é declarável em uma página.

Falhando qualquer um dos seis, constrói-se a versão fina deste documento e adotam-se as quatro peças de mercado acima. Passando os seis, o Wolverine é a melhor opção disponível e este documento vira a especificação de como configurá-lo — o contrato da § Entrega não muda em nenhum dos dois caminhos, que é exatamente o que IOutboxTransport e IIntegrationEventMapper compram.

Veredito e sequência

A assimetria que decide

Risco separado · dependências que mudaram de licença

O levantamento trombou num achado que não é deste épico, mas é do repositório. As duas dependências têm o mesmo dono e o mesmo modelo de licença — e mesmo assim recebem decisões opostas, porque o que decide não é a licença: é urgência × custo de saída.

O plano do AutoMapper · Mapperly

Descer de versão não é opção: leva à CVE aberta, que o gate de SCA do ADR 0001 acusaria no primeiro build. Registrar a Community License é paliativo — o critério é da organização que usa, e num framework distribuído a terceiros isso é dívida repassada a quem não escolheu a dependência. Sobra remover, e o substituto tem nome.

Escopo da ADR 0014, para não contaminar este épico: GrydCrud.Mapperly ao lado do GrydCrud.AutoMapper existente; GrydReports troca um profile e cinco handlers; remoção do pacote do Directory.Packages.props; e o teste que já existe em GrydCrud.AutoMapper.Tests passa a rodar contra a implementação nova. O MediatR não entra nessa ADR — é outra escala e outra decisão.

Fontes do levantamento, todas conferidas em 09/09/2026: anúncio das edições comerciais de AutoMapper e MediatR (Jimmy Bogard) e a FAQ de licenciamento da Lucky Penny; a página de licença do MassTransit v9 na Massient; a página de produtos da JasperFx; o repositório do DotNetCore.CAP e a documentação de outbox EF Core do Brighter; o aviso GHSA-rvv3-g6hj-g44x e a análise do impacto na última versão livre do AutoMapper; a documentação de durabilidade, filas locais e eventos de domínio do Wolverine.

A pergunta de saída

Por que a pergunta importa: o MediatR 12.x é livre indefinidamente mas está congelado — sem updates nem suporte —, e o Wolverine é o sucessor natural. Se ele couber, traz junto o outbox transacional com filas locais duráveis sem broker, e as features F3 a F6 deste épico deixam de precisar existir. Se não couber, o Gryd.IO constrói a versão fina especificada aqui e a decisão fica registrada como escolha, não como omissão.

O terreno · evidência já levantada

Conferido em feature/grydfiles-modulo-plataforma · 879dd954 · 09/09/2026. Não é preciso redescobrir nada disto.

Os três marcados como críticos, mais o critério 6, são o spike inteiro. Se eles couberem, os outros nove são mecânicos e não precisam ser portados para responder à pergunta. Se um deles não couber, a resposta é não e os outros nove não importam.

Arquivos para ler primeiro

src/Core/Gryd.Application/Behaviors/TenantScopeBehavior.cs
src/Modules/Auth/GrydAuth.Application/Common/Behaviors/PermissionAuthorizationBehavior.cs
src/Modules/Auth/GrydAuth.Application/Common/Behaviors/CrossTenantDataFilterBehavior.cs
src/Core/Gryd.Infrastructure/Tenancy/TenantContextAccessor.cs      # o AsyncLocal
src/Core/Gryd.Infrastructure/Tenancy/TenantQueryFilterExtensions.cs # o query filter global
src/Core/Gryd.Domain/Primitives/AggregateRoot.cs                    # o alvo do scraping
src/Modules/Auth/GrydAuth.Infrastructure/Data/GrydAuthDbContext.cs  # o laço a substituir
src/Core/Gryd.API/Extensions/ServiceCollectionExtensions.cs         # 1 dos 8 AddMediatR

Passo a passo

1. Branch spike/wolverine-sucessor-mediatr, a partir de feature/grydfiles-modulo-plataforma. Não sai dela para lugar nenhum.
2. Escolher um caso de uso só, e que atravesse os três behaviors críticos — um comando do GrydAuth que exija permissão e tenha alcance entre tenants. Migrar mais de um não responde melhor à pergunta; só custa mais.
3. Subir o Wolverine com persistência em PostgreSQL e UseEntityFrameworkCoreTransactions(), ao lado do MediatR, sem removê-lo. Os dois convivem no spike.
4. Portar os três behaviors como middleware do Wolverine, preservando a ordem — que hoje é significativa e é a hipótese sob teste.
5. Ligar o scraping de eventos do AggregateRoot (PublishDomainEventsFromEntityFrameworkCore) sem alterar as 74 chamadas a AddDomainEvent.
6. Rodar os testes de integração de tenancy que já existem contra o caminho novo, com Testcontainers e PostgreSQL real. Não escrever testes novos: os que existem são o critério, e é exatamente por isso que eles servem.
7. Provar o pós-commit: um handler registra o instante em que rodou, o caso de uso registra o instante do commit, e a asserção é handler > commit.
8. Escrever o relatório — uma página, formato abaixo — e parar.

Os seis critérios de saída

O que o spike não faz

• Não migra os 199 arquivos. Migra um caso de uso.
• Não remove o MediatR, nem toca nos oito pontos de AddMediatR.
• Não implementa o outbox do Nexio, nem o GrydMessaging.
• Não toca no GrydFiles, no GrydReports nem no GrydCrud.
• Não resolve o AutoMapper — isso é a ADR 0014 e corre em paralelo, sem dependência.
• Não faz merge. A entrega é conhecimento, não código.

O relatório · uma página, seis respostas

1. VEREDITO           sim | não        (uma palavra, na primeira linha)
2. CRITÉRIOS          os seis, com passou/falhou e a evidência de cada um
3. ONDE DOEU          o que exigiu contorno, e qual contorno
4. TENANCY            o que aconteceu com AsyncLocal, query filter e ordem
5. CUSTO ESTIMADO     semanas para os 199 arquivos, com o método da estimativa
6. RECOMENDAÇÃO       adotar agora | adotar depois, com gatilho | não adotar

Contexto opcional, para quem quiser: a § Alternativas de mercado tem o levantamento completo e o motivo de o Wolverine ser o único candidato; a § Contratos do núcleo tem o que o Gryd.IO construiria caso a resposta seja não. Nenhuma das duas é pré-requisito para executar este roteiro.

1. Firmar contratos e propriedade de tabelas/migrações; inventariar efeitos existentes.
2. Implementar e testar coleta por transação na plataforma, inclusive rollback e commit incerto.
3. Implementar outbox do produtor, lease, cabeça por agregado, inbox e operação.
4. Publicar pacote, consumir no Nexio e validar composição real dos quatro perfis.
5. Executar cenários de falha e restauração com PostgreSQL e transporte reais antes do primeiro cliente.

Wolverine permanece experimento histórico; sua adoção exige nova decisão e não é pré-requisito deste caminho.

O repositório mantém ADRs numeradas em docs/adr/, hoje até a 0009. Cinco decisões deste documento merecem registro próprio, porque são decisões de plataforma que produtos futuros vão herdar sem ter participado da conversa.

• Broker de mensagens. RabbitMQ, Kafka, Service Bus. O IEventBus que já existe no Gryd.Infrastructure.Abstractions continua sem implementação, e este épico não a traz — o outbox entrega a um IOutboxTransport, e um transporte que fale com broker é trabalho de quem tiver um.
• Entrega exatamente uma vez. Não é oferecida e não será. Ver § Entrega.
• Event sourcing. O outbox não é store de eventos: a mensagem entregue é expurgada e o estado continua vivendo nas tabelas do agregado.
• Saga e coreografia de processo. Compensação, timeout de processo longo e máquina de estados distribuída são outro problema, e resolvê-los sem antes ter entrega garantida seria construir o segundo andar.
• Inbox como dedupe global. O IInboxGuard é por consumidor, não por sistema. Dois consumidores da mesma mensagem processam os dois, e é isso que se espera.
• Reordenar mensagem presa. Não há "pular esta e continuar". Destravar uma chave é descartar explicitamente, com motivo e trilha.
• Retenção do AuditLog. Fora deste épico; a coluna Action entra sem mexer na política de guarda da trilha.