@softize/opus 20.0.0 → 21.0.0

package/docs/adr/0028-schedules-run-actions-as-the-system-by-action-opt-in.md

@@ -0,0 +1,127 @@
+# ADR 0028 — Schedules executam actions como o sistema, por opt-in da action
+
+- **Status:** aceita (21.0.0).
+- **Data:** 2026-09-26.
+
+## Contexto
+
+Um schedule executa a action com `user: null` e um `can` que nega tudo. Para o runtime, isso é
+indistinguível de um chamador anônimo: a action alvo só roda se declarar `public: true`. A
+documentação ensinava a combinar `public: true` com `internal: true`, para que os servidores do Opus
+não a expusessem por HTTP. O contorno tem três defeitos:
+
+- `public: true` declara que a action não exige identidade, o contrário do que se quer dizer;
+- `internal` só protege nos servidores do Opus; outro transporte que chame `runtime.execute` expõe
+  uma action pública sem autenticação;
+- o `authorize` da action não distingue o sistema de um anônimo, porque os dois chegam com
+  `user: null`.
+
+O contrato já tem, sem efeito até aqui, o campo `automatable`, documentado no protocolo como
+“sistema/cron/workflow pode disparar”. A provenance `schedule` e o `actor.type: 'system'` do audit
+também já existem.
+
+Restrições dadas pelo dono, inegociáveis: nada que hoje exige usuário passa a ser executável por
+HTTP sem usuário; o acesso do sistema é opt-in por action e negado por padrão; `authorize` e
+`requires` enxergam que o ator é o sistema; o audit registra o ator.
+
+## Decisão
+
+1. **O opt-in é `automatable: true` no contrato da action.** O campo existente passa a ter efeito:
+   uma action automatizável aceita execução pelo sistema sem usuário. Sem ele, a execução pelo
+   sistema de uma action não pública é recusada com `auth.system_forbidden` (categoria
+   `authorization`). O opt-in fica no contrato, e não no schedule, para que quem é dono da action
+   decida e para que o manifest, que passa a projetar `automatable`, mostre a decisão a quem revisa.
+2. **Só o runtime cria a identidade de sistema.** O disparo de um schedule executa a action por um
+   caminho interno do runtime, marcado como execução do sistema; `runtime.execute` não aceita essa
+   marca. Um `ContextBase` com `provenance: { kind: 'schedule' }` vindo de fora continua sendo, sem
+   usuário, um chamador anônimo. Um job em background preserva a identidade por uma marca
+   explícita no envelope, `ctx.system: true`, que o runtime grava ao enfileirar somente quando a
+   execução que enfileira é do sistema (`isSystemActor`). O worker exige essa marca e `userId: null`;
+   a provenance original não conta, porque vem do chamador de `runtime.execute` e pode dizer
+   `schedule` sem que um schedule tenha disparado. Pelo mesmo motivo, uma tool chamada por
+   `ctx.ai` dentro de uma action agendada não herda a identidade, nem no job que ela enfileira.
+3. **A identidade reaproveita o contexto existente.** Na execução pelo sistema, `ctx.user` é `null`
+   (não há pessoa), `ctx.can` nega toda permissão e `ctx.provenance` é
+   `{ kind: 'schedule', scheduleName }` — ou `background` com essa provenance original. O helper
+   `isSystemActor(ctx)`, exportado pelo core, responde se o ator é o sistema, para que um
+   `authorize` possa aceitá-lo de forma explícita: `(ctx) => isSystemActor(ctx) ||
+   ctx.can('caixa:fechar')`. O helper não lê a provenance, que qualquer código servidor pode
+   preencher: ele consulta um registro interno dos contextos que o próprio runtime criou para o
+   sistema. `requires` continua declarativo: o sistema não detém permissões, e o manifest mostra
+   `automatable` ao lado de `permission`.
+4. **O audit registra o ator como sistema.** O registro de uma execução pelo sistema traz
+   `actor: { id: null, type: 'system' }` e a provenance com o nome do schedule, como já acontecia
+   com actions públicas agendadas.
+5. **O `start()` recusa schedules que não vão rodar.** Um schedule ativo cuja action não é `public`
+   nem `automatable` interrompe o boot com `runtime.schedule_action_not_automatable`, antes de
+   inicializar os adapters, como `runtime.schedule_action_not_found`. A mensagem lista cada schedule
+   e a action, e indica as duas saídas: `automatable: true` no contrato ou `enabled: false` no
+   schedule. Um aviso deixaria o processo subir com um agendamento que falha em todo disparo; o
+   custo de quebrar o boot de quem tem essa configuração foi aceito junto com a versão major
+   (21.0.0), que já reúne as outras mudanças incompatíveis desta decisão e da ADR 0026.
+
+`public: true` continua funcionando para actions agendadas e mantém o comportamento de hoje; a
+documentação passa a recomendar `automatable: true`.
+
+## Consequências
+
+- Uma action pode ser agendada sem ficar aberta a anônimos. `internal: true` deixa de ser
+  necessário para esse fim e volta a significar só “não expor por REST”.
+- Um `authorize` que delega a `ctx.can` recusa o sistema até aceitá-lo com `isSystemActor(ctx)`.
+  São duas decisões explícitas — `automatable` e a regra no `authorize` — quando a action tem
+  autorização própria; sem `authorize`, `automatable` basta.
+- Uma chamada de IA feita pelo handler de uma action agendada (`ctx.ai.run`) não herda a identidade
+  de sistema: as tools passam por `runtime.execute`, como qualquer chamador.
+- `actions` que já declaravam `automatable: true` passam a aceitar execução por schedule. Como só um
+  schedule registrado no próprio runtime cria a identidade, nenhuma rota HTTP ganha acesso.
+- O harness `runAction` ganha a opção `schedule`, que executa a action como o sistema com a mesma
+  regra do runtime.
+- No worker, a identidade vem do envelope do job, como o `userId` já vinha. Escrever diretamente na
+  fila fica **fora do modelo de ameaça** desta decisão: quem tem esse acesso já forja o `userId` de
+  qualquer pessoa, e a marca `system` não amplia o que ele alcança. A fronteira de confiança da fila
+  não muda; protegê-la é papel da infraestrutura (credenciais do Redis, rede).
+- Um schedule sem opt-in, que antes subia e falhava em cada disparo com `auth.unauthenticated`,
+  agora impede o boot. `auth.system_forbidden` continua existindo para o caso que o boot não
+  detecta: um job do sistema cuja action perdeu `automatable` entre o enfileiramento e o worker.
+
+## Alternativas descartadas
+
+### Um usuário sintético de sistema em `ctx.user`
+
+Deixaria `authorize` existente funcionar sem mudança. Foi descartada porque um `authorize` que
+testa apenas `ctx.user !== null` passaria a aceitar o sistema sem que ninguém decidisse isso, e
+porque um id sintético se misturaria aos ids de pessoas no audit.
+
+### Opt-in no schedule
+
+Colocaria a decisão ao lado do agendamento. Foi descartada porque o schedule concederia acesso a uma
+action que ele não possui, e porque o contrato da action — e o manifest — deixariam de mostrar quem
+pode executá-la.
+
+### Um campo novo `ctx.actor` ou um tipo de identidade próprio
+
+Tornaria a identidade mais evidente. Foi adiado: provenance e `user: null` já descrevem o ator sem
+ambiguidade quando só o runtime cria a execução pelo sistema, e um campo novo exigiria migração em
+todos os consumidores do contexto.
+
+### Um `can` de sistema que concede permissões configuráveis
+
+Resolveria `authorize` baseado em `ctx.can`. Foi descartada por ora porque criaria uma política de
+permissões do sistema paralela à do app; a regra explícita no `authorize` é mais fácil de revisar.
+
+### Só avisar no boot quando o schedule aponta para action não automatizável
+
+Foi a proposta inicial: não quebraria projetos que sobem hoje. Foi descartada na decisão do dono,
+porque o processo subiria com um schedule que falha em todo disparo e o aviso se perde no log; como
+a versão já é major, a falha no boot fica coerente com `runtime.schedule_action_not_found`.
+
+## Verificação
+
+`tests/core/system-actor.test.ts` confere, pela fronteira do runtime: schedule com action
+`automatable` executa sem `public`; `runtime.execute` sem usuário, mesmo com provenance `schedule`,
+continua recusado; `isSystemActor` é verdadeiro só na execução pelo sistema, inclusive no job em
+background criado por schedule, e falso para uma provenance `schedule` montada fora do runtime —
+também no job que essa chamada enfileira e na tool em background chamada por `ctx.ai` dentro de uma
+action agendada; a falha de boot antes da inicialização dos adapters, inclusive com schedule
+desabilitado ignorado; a recusa `auth.system_forbidden` de um job do sistema para action sem
+opt-in; e o harness `runAction` com a opção `schedule`.

package/docs/protocol.md

@@ -98,7 +98,7 @@ type ActionBase<In, Out> = {
 
   // — Integração —
   ai?:             boolean | AIConfig   // default true (opt-out via false)
-  automatable?:    boolean              // sistema/cron/workflow pode disparar
+  automatable?:    boolean              // schedule pode executar como o sistema (§4, ADR 0028)
   internal?:       boolean              // só service-to-service; não expõe REST
   successStatus?:  number               // HTTP code de sucesso (default 200)
 }
@@ -606,6 +606,20 @@ O Opus **não autentica** — não valida token, não emite sessão. O adapter (
 
 Se `ctx.user` é `null` e `public !== true`, runtime rejeita com `{ code: 'auth.unauthenticated', category: 'authentication' }` **antes** dos loaders e de `authorize`. Assim um chamador anônimo não dispara consultas nem descobre, pelo erro de um loader, se um registro existe.
 
+### Identidade de sistema
+
+O disparo de um schedule executa a action **como o sistema**: `ctx.user` é `null`, `ctx.can` nega toda permissão e `ctx.provenance` é `{ kind: 'schedule', scheduleName }` (ou `background` com essa provenance original, no job que o schedule enfileirou). Só o runtime cria essa execução; `runtime.execute` não a aceita de fora, mesmo com uma provenance `schedule`. O job carrega a identidade pela marca `JobSpec.ctx.system`, gravada no enfileiramento só quando a execução é do sistema; o worker não a deduz da provenance.
+
+O acesso do sistema é **opt-in por action** e negado por padrão. Sem usuário, o gate de autenticação aceita o sistema apenas quando a action declara `automatable: true`; nas demais, responde `{ code: 'auth.system_forbidden', category: 'authorization' }`. Uma action `public: true` continua aceitando qualquer chamador, inclusive o sistema.
+
+`isSystemActor(ctx)` responde se o ator é o sistema. Ele consulta um registro interno dos contextos que o runtime criou, e não a provenance. Como o sistema não detém permissões, um `authorize` que delega a `ctx.can` o aceita de forma explícita, numa closure — a DSL em string não expressa isso, e `ctx.provenance` não serve como teste de sistema, porque o chamador de `runtime.execute` pode preenchê-la:
+
+```ts
+authorize: (ctx) => isSystemActor(ctx) || ctx.can('caixa:fechar')
+```
+
+`requires` continua declarativo; o manifest projeta `automatable` ao lado de `permission`. O audit registra `actor: { id: null, type: 'system' }`. Ver ADR 0028.
+
 ---
 
 ## 5. Contrato de audit
@@ -719,6 +733,10 @@ registerAuditSink({
 
 Múltiplos sinks são permitidos. Action sem `audit.sink` emite para todos os sinks registrados; com `audit.sink: 'compliance'` emite só pro sink nomeado.
 
+### Registros de reaction
+
+Reactions também auditam: um registro por entrega que chega ao handler, com `action` igual ao nome da reaction, `provenance.kind: 'reaction'`, `meta: { kind: 'reaction', attempts }`, sem `actionKind` e com `input: { event: { id, type, source } }` — sem o payload, que já está no audit da action emissora. Registros de reaction vão para todos os sinks. Ver §12.
+
 ### Falha de sink
 
 Falha ao emitir audit **não** falha a action. Sink lançou → opus loga `{ code: 'audit.sink.failed', cause: <error> }` no logger configurado e continua. Persistência de audit é responsabilidade do sink (retry, fila, etc).
@@ -1517,10 +1535,16 @@ type DomainEvent<T = unknown> = {
   tenant?:   string | null
   data:      T                          // payload (livre, handler decide)
   source:    {
-    action:      string                 // 'deal.archive'
-    actionId:    string                 // bate com AuditRecord.id
+    action:      string                 // action que iniciou a cadeia ('deal.archive')
+    actionId:    string                 // bate com AuditRecord.id dessa action
     correlation?: string                // request id / trace
   }
+  cause?:    {                          // só em evento publicado por reaction (§12)
+    reaction:  string                   // reaction que publicou
+    eventId:   string                   // evento que ela processava
+    eventType: string
+    depth:     number                   // 1 = primeira reaction depois da action
+  }
   trace?:    TraceContext                 // propagado para reactions/consumidores
   meta?:     Record<string, unknown>
 }
@@ -1577,10 +1601,11 @@ type ReactionDef<Event = unknown> = {
   // — Execução —
   handler: (ctx: ReactionContext, event: DomainEvent<Event>) =>
              Promise<void> | void
+  emits?:  string[]                             // eventos que o handler pode publicar
   
   // — Resiliência —
-  retry?:       { attempts: number, backoff?: BackoffSpec }
-  timeout?:     number                          // ms
+  retry?:       { attempts: number, backoff?: BackoffSpec }  // attempts = total de execuções
+  timeout?:     number                          // ms por tentativa; aborta ctx.signal
   dedup?:       (event: DomainEvent<Event>) => string  // chave de idempotência
   concurrency?: number                          // máx execuções paralelas (default 1)
   
@@ -1628,16 +1653,21 @@ type ReactionContext = {
   user:     User | null              // ator que disparou o evento (pode ser system)
   tenantId: string | null
   db:       unknown                  // mesmo data adapter
-  emit:     EmitFn                   // descarta o evento sem publicar (sem encadeamento)
+  emit:     EmitFn                   // publica só os eventos de `emits` (encadeamento limitado)
   log:      LoggerAdapter            // logger pre-bound com contexto da reaction
   storage:  StorageAdapter | null    // storage de arquivos (experimental)
   provenance: Provenance             // { kind: 'reaction', … }
   trace?:   TraceContext             // span filho do evento recebido
   meta:     Record<string, unknown>
+  signal?:  AbortSignal              // abortado quando a tentativa excede `timeout`
 }
 ```
 
-Uma reaction não encadeia outra por evento: dentro dela, `ctx.emit` descarta o evento sem publicá-lo. Com `config.dev` ativo, cada descarte registra o aviso `runtime.reaction_emit_ignored` no log; em produção, o descarte é silencioso. Quando outro consumidor precisa desse fato, emita o evento no handler da action que o produz e declare-o em `emits`.
+### Encadeamento
+
+Uma reaction publica com `ctx.emit` somente os eventos listados no seu `emits`. Qualquer outro evento, inclusive de reaction sem `emits`, é descartado com o aviso `runtime.reaction_emit_ignored`, controlado por `config.warnUndeclaredEmits`. O evento publicado herda `actor`, `tenant` e `source` do evento recebido e ganha `cause: { reaction, eventId, eventType, depth }`.
+
+Uma cadeia dá no máximo `config.maxReactionDepth` saltos (default 5). O `ctx.emit` que passaria do limite não publica e registra o erro `runtime.reaction_chain_too_deep`; com `emitMode: 'strict'`, o mesmo código interrompe a reaction. Falha de `publish` segue `emitMode`, como nas actions. Ver ADR 0027.
 
 ### Setup unificado
 
@@ -1663,20 +1693,20 @@ await runtime.start()
 
 ### Resiliência: quem implementa o quê
 
-| Campo         | Implementação                            | Sem suporte do adapter      |
-|---------------|------------------------------------------|------------------------------|
-| `dedup`       | Core — cache LRU de `event.id` por reaction (TTL configurável) | Sempre funciona |
-| `retry`       | Adapter preferencial (Inngest, BullMQ); core fallback simples (in-memory backoff) | Warn em setup; core fallback ativo |
-| `timeout`     | Core — AbortController em volta do handler | Sempre funciona |
-| `concurrency` | Adapter (consumer groups); core fallback (semáforo) | Default `concurrency: 1` |
+| Campo         | Implementação no core (ADR 0026) |
+|---------------|----------------------------------|
+| `dedup`       | Chave por reaction, em memória: ocupada da chegada até o fim da entrega e, após sucesso, por `config.dedupCacheTtl` (default 60 s), com no máximo `config.dedupCacheMaxEntries` chaves concluídas por reaction (default 10.000; a mais antiga sai primeiro). Falha definitiva libera a chave. Duplicata vira `debug` `runtime.reaction_duplicate_skipped`. |
+| `retry`       | Em memória. Sem `retry`, uma execução (`config.defaultRetry` vale só para background). Exceções comuns e timeout repetem. `ActionError` segue `retriable`, cujo padrão vem da categoria: só `rate_limit` e `dependency` repetem (`internal` não); `error({ ..., retriable: true })` força a repetição. Cada repetição avisa `runtime.reaction_retry`. |
+| `timeout`     | `AbortController` por tentativa: aborta `ctx.signal` e falha com `runtime.reaction_timeout` (retriable). A vaga é liberada no timeout. |
+| `concurrency` | Semáforo por reaction (default 1) e global (`config.maxConcurrentReactions`, default 10), em ordem de chegada. A espera entre tentativas não ocupa vaga. |
 
-Reaction declara intenção; runtime aplica o que core garante + delega o que adapter suporta. Se adapter não cobre algo declarado, **warning visível no boot** (não silencia falha de capability).
+As políticas valem por processo. Delegar retry e concorrência a um adapter durável (consumer groups, filas) fica para quando existir driver distribuído. Valores inválidos falham no registro com `runtime.invalid_reaction_policy` ou na criação do runtime com `runtime.invalid_config`.
 
 ### Falha de reaction não afeta o emissor
 
 Reaction roda **assíncrono** ao handler que emitiu o evento. Se reaction falha, é problema dela (retry / dead-letter via adapter); a action que emitiu o evento já completou.
 
-Falhas registradas no log do runtime + audit (entrada do tipo `'reaction.failed'`). Adapter de eventos pode rotear pra dead-letter (v1).
+Falhas definitivas são registradas no log do runtime (`reaction failed`, com o número de tentativas) e no audit (registro com `outcome: 'error'`). Adapter de eventos pode rotear pra dead-letter (v1).
 
 ### Pipeline de uma reaction
 
@@ -1684,14 +1714,14 @@ Falhas registradas no log do runtime + audit (entrada do tipo `'reaction.failed'
 EventBusAdapter recebe evento (publish externo ou ctx.emit interno)
    ↓
 matching: encontra reactions registradas pra esse padrão
-   ↓ (paralelo, com concurrency limit)
 para cada reaction:
-   ↓ (a) dedup check (se declarado)
-   ↓ (b) authorize (se declarado)
+   ↓ (a) dedup: reserva a chave na chegada (se declarado)
+   ↓     espera vaga da reaction e vaga global (concurrency)
+   ↓ (b) authorize, uma vez (se declarado)
    ↓ (c) handler executa (com timeout)
-   ↓ (d) ctx.emit dentro da reaction não publica (descartado, com aviso em dev)
-   ↓ (e) audit (reaction completed/failed)
-   ↓ (f) retry se falhou e config permite
+   ↓ (d) ctx.emit publica os eventos declarados em `emits`, até a profundidade máxima
+   ↓ (e) retry se falhou e a política permite (libera as vagas durante a espera)
+   ↓ (f) audit, um registro por entrega (completed/failed, com as tentativas)
 ```
 
 ### O que **não** entra em v0
@@ -1758,6 +1788,7 @@ type RuntimeConfig = {
 
   // — Resiliência / dedup —
   dedupCacheTtl?:        number               // ms, default 60_000
+  dedupCacheMaxEntries?: number               // chaves concluídas por reaction, default 10_000
   defaultRetry?:         { attempts: number, backoff?: BackoffSpec }
 
   // — i18n —
@@ -1768,7 +1799,8 @@ type RuntimeConfig = {
 
   // — Limites —
   maxConcurrentActions?:    number            // default Infinity
-  maxConcurrentReactions?:  number            // default 10
+  maxConcurrentReactions?:  number            // default 10, somando todas as reactions
+  maxReactionDepth?:        number            // default 5 saltos de reaction por cadeia
 }
 ```
 
@@ -1831,9 +1863,11 @@ Se você não passa `config`, o runtime usa:
   validateOutputInDev:  true,
   warnUndeclaredEmits:  true,
   dedupCacheTtl:        60_000,
+  dedupCacheMaxEntries: 10_000,
   defaultRetry:         { attempts: 3, backoff: { kind: 'exponential', initialMs: 1000 } },
   maxConcurrentActions:   Number.POSITIVE_INFINITY,
   maxConcurrentReactions: 10,
+  maxReactionDepth:       5,
 }
 ```
 
@@ -2134,12 +2168,14 @@ chamada, inclusive por IA e MCP.
 - **`QueueAdapter`** — adapter que executa background jobs. Ver §8/§10.
 - **`ctx.emit`** — função disponível no contexto do handler para emitir eventos declarados em `emits`. Ver §11.
 - **`requires`** — permissão declarativa (string ou array) usada por adapters de docs/OpenAPI. Distinta de `authorize` (lógica runtime). Ver §4.
-- **`automatable`** — flag que indica se a action pode ser disparada por sistema (cron, workflow, trigger). Distinta de `ai.enabled`. Ver §2.
+- **`automatable`** — opt-in que permite a um schedule executar a action como o sistema, sem usuário. Negado por padrão; não abre a action a anônimos. Distinta de `ai.enabled`. Ver §4.
+- **`isSystemActor(ctx)`** — responde se a execução foi criada pelo runtime para o sistema (schedule ou job que ele enfileirou). Usado no `authorize` de actions `automatable`. Ver §4.
 - **`internal`** — flag que indica action service-to-service apenas; server adapter não expõe como REST público. Ver §2.
 - **Reaction** — declaração que escuta evento(s) e executa handler. Auto-registrada pelo runtime via EventBusAdapter. Pareada com Action (ator inicia × sistema reage). Ver §12.
 - **`defineReaction`** — função que constrói uma reaction declarativa.
 - **`ReactionContext`** — contexto entregue ao handler de reaction (user, tenant, db, emit, log, meta).
-- **`dedup`** — função em reaction que produz chave de idempotência; runtime descarta evento já processado. Ver §12.
+- **`dedup`** — função em reaction que produz chave de idempotência; runtime descarta evento com chave em processamento ou processada dentro de `dedupCacheTtl`. Ver §12.
+- **`cause`** — campo de `DomainEvent` publicado por reaction: reaction, evento de origem e profundidade na cadeia. Ver §11/§12.
 - **`LoggerAdapter`** — interface de logger plugável (levels, structured, child binding). Default: `@softize/opus/log-console`. Ver §8.
 - **`RuntimeConfig`** — behavior knobs do runtime (auditMode, emitMode, env, i18n, limits). Recebe valores literais; core nunca lê env direto. Ver §14.
 - **`healthCheck()`** — método opcional em qualquer adapter, retorna `{ ok, details? }`. Agregado por `runtime.healthCheck()` e exposto em `/ready`. Ver §8.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softize/opus",
-  "version": "20.0.0",
+  "version": "21.0.0",
   "description": "End-to-end action protocol for TypeScript. Single package with subpath exports (core + adapters).",
   "license": "MIT",
   "type": "module",

package/src/core/audit.ts

@@ -61,7 +61,8 @@ export class AuditEmitter {
     if (targetSinks.length === 0) return
 
     const results = await Promise.allSettled(
-      targetSinks.map((sink) => Promise.resolve(sink.emit(processed))),
+      // `then` também captura o sink que lança de forma síncrona: toda falha vira rejeição tratada.
+      targetSinks.map((sink) => Promise.resolve().then(() => sink.emit(processed))),
     )
 
     const failures = results.filter(

package/src/core/index.ts

@@ -216,7 +216,7 @@ export type {
 export { AuditEmitter } from './audit.ts'
 
 // — Runtime ———————————————————————————————————————————————————————————————————
-export { Runtime, createRuntime } from './runtime.ts'
+export { Runtime, createRuntime, isSystemActor } from './runtime.ts'
 export type {
   RuntimeSetup,
   RuntimeSetupConfig,

package/src/core/reactions.ts

@@ -27,7 +27,7 @@ export function defineReaction<Event = unknown>(
 // =============================================================================
 
 /** Campos server-only que o `bindReaction` fornece — o resto é a DECLARAÇÃO (isomorfa). */
-type ReactionBindingKeys = 'handler' | 'retry' | 'timeout' | 'dedup' | 'concurrency'
+type ReactionBindingKeys = 'handler' | 'emits' | 'retry' | 'timeout' | 'dedup' | 'concurrency'
 
 /**
  * A DECLARAÇÃO de uma reação, autorável na sessão de design (isomorfa, SEM efeito): qual
@@ -36,9 +36,13 @@ type ReactionBindingKeys = 'handler' | 'retry' | 'timeout' | 'dedup' | 'concurre
  */
 export type ReactionContract<Event = unknown> = Omit<ReactionDef<Event>, ReactionBindingKeys>
 
-/** Parte server-only amarrada por `bindReaction`: o handler + a config de entrega. */
+/**
+ * Parte server-only amarrada por `bindReaction`: o handler, os eventos que ele publica e a
+ * política de entrega. Como no `bindAction`, `emits` fica no binding, ao lado do handler.
+ */
 export interface ReactionBinding<Event = unknown> {
   handler: ReactionHandlerFn<Event>
+  emits?: string[]
   retry?: { attempts: number; backoff?: BackoffSpec }
   timeout?: number
   dedup?: (event: DomainEvent<Event>) => string