@softize/opus 20.1.0 → 21.0.0

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.1.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