@softize/opus 20.1.0 → 21.0.1

package/CHANGELOG.md

@@ -7,6 +7,111 @@ Depois de qualquer bump, rode os gates (`typecheck` · `test` · `opus check` ·
 `opus copy --check` · `base copy check` · `manifest:check`) — eles apontam o que a
 mudança cobra do seu código.
 
+## 21.0.1 — 2026-09-26
+
+**Correção.** O `status()` do driver BullMQ podia devolver `status: 'done'` com `data: null` para um
+job que concluiu com resultado. O driver lia o job e depois o estado em duas consultas separadas;
+quando o worker terminava entre as duas, o estado já era terminal e o job lido ainda era o do
+processamento, sem resultado. Quem acompanhava o job por polling encerrava a espera sem o
+resultado e não voltava a consultar. O mesmo valia para `failed` sem o motivo. Agora, quando o
+estado é terminal e o job lido ainda não traz a conclusão, o driver relê o job antes de montar o
+handle. Nenhuma mudança é necessária no seu código.
+
+## 21.0.0 — 2026-09-26
+
+As reactions passam a fazer o que a declaração promete. `retry`, `timeout`, `dedup` e
+`concurrency`, aceitos desde as primeiras versões e ignorados até aqui, agora valem em cada evento
+entregue, e cada entrega que chega ao handler entra no audit (ADR 0026). Uma reaction pode publicar
+os eventos que declara em `emits`, numa cadeia com profundidade limitada (ADR 0027). E um schedule
+executa como o sistema uma action que declara `automatable: true`, sem precisar abri-la com
+`public: true` (ADR 0028). É major porque algumas dessas mudanças podem interromper o boot ou mudar
+o ritmo de uma aplicação que funcionava na 20.1.0: a seção **Breaking** diz o que fazer em cada
+uma. Outros pontos podem pedir ajuste sem interromper a aplicação:
+
+- os sinks de audit passam a receber registros de reactions, com `provenance.kind: 'reaction'`,
+  `meta.kind: 'reaction'` e sem `actionKind`. Um sink que conta ou filtra registros por action ou
+  por `actionKind` deve tratá-los à parte;
+- o manifest ganha `automatable` em cada action e `emits` em cada reaction: rode `opus gen` para
+  que o `manifest:check` volte a passar;
+- o aviso `runtime.reaction_emit_ignored` passa a seguir `config.warnUndeclaredEmits`, e não
+  `config.dev`. Com os padrões, nada muda.
+
+### Breaking
+
+**Política de reaction ou config do runtime fora do domínio derruba o boot.** Valores que o runtime
+ignorava passam a ser conferidos. `retry.attempts`, `concurrency` ou `timeout` de uma reaction com
+zero, número negativo ou fracionário, como `retry: { attempts: 0 }` ou `concurrency: 0`, interrompem
+o registro com `runtime.invalid_reaction_policy`. `maxConcurrentReactions`, `dedupCacheTtl` e os
+novos `maxReactionDepth` e `dedupCacheMaxEntries` inválidos, como `dedupCacheTtl: Infinity` ou
+`maxConcurrentReactions: 0`, interrompem o `createRuntime` com `runtime.invalid_config`. A mensagem
+nomeia a reaction e cada campo. Migração: corrija o valor ou remova o campo para usar o padrão. Rode
+o `start()` num teste para descobrir antes do deploy.
+
+**Reactions passam a ser serializadas.** Sem `concurrency` declarado, cada reaction processa um
+evento por vez, na ordem de chegada, e todas as reactions do processo somam no máximo 10 execuções
+simultâneas. Antes, cada evento rodava assim que chegava, sem limite. Uma reaction que dependia de
+rodar eventos em paralelo fica mais lenta, e um handler sem `timeout` que trava segura a única vaga
+e para a reaction inteira. Migração: declare `timeout` em toda reaction que depende de algo externo;
+declare `concurrency` onde o paralelismo é necessário; aumente `config.maxConcurrentReactions` se o
+teto global limitar a vazão.
+
+**Schedule sem opt-in derruba o boot.** Um schedule ativo que aponta para uma action sem `public` nem
+`automatable` interrompe o `start()` com `runtime.schedule_action_not_automatable`, antes de
+inicializar os adapters. Antes, o processo subia e cada disparo falhava com `auth.unauthenticated`.
+Migração: declare `automatable: true` no contrato da action para que o schedule a execute como o
+sistema, ou `enabled: false` no schedule para mantê-lo sem executar.
+
+**`auth.system_forbidden` substitui `auth.unauthenticated` na execução pelo sistema.** Uma execução
+iniciada por schedule, inclusive o job em background que ele enfileira, que chega a uma action sem
+opt-in termina em `auth.system_forbidden` (categoria `authorization`). Com a falha no boot, isso só
+acontece com um job enfileirado antes de a action perder `automatable`. Migração: alertas e
+consultas de audit que filtravam `auth.unauthenticated` para schedules passam a filtrar o código
+novo.
+
+### Reactions
+
+- **Entrega:** `dedup` reserva a chave na chegada, descarta a mesma chave enquanto a entrega está em
+  andamento e por `config.dedupCacheTtl` depois do sucesso, e a libera se a entrega falhar em
+  definitivo; cada reaction guarda no máximo `config.dedupCacheMaxEntries` chaves concluídas
+  (padrão 10.000). `concurrency` (padrão 1) e `config.maxConcurrentReactions` (padrão 10) limitam as
+  execuções simultâneas. `timeout` aborta o novo `ctx.signal` e encerra a tentativa com
+  `runtime.reaction_timeout`. `retry.attempts` conta o total de execuções, com backoff `fixed` ou
+  `exponential`. Exceções comuns e timeouts repetem; um `ActionError` segue o `retriable` da
+  categoria (só `rate_limit` e `dependency` repetem por padrão) ou o declarado. Sem `retry`, o handler
+  roda uma vez: `config.defaultRetry` continua valendo só para jobs em background.
+- **Observação:** cada tentativa repetida gera o aviso `runtime.reaction_retry`; a falha definitiva
+  gera `reaction failed` com o número de tentativas; um evento descartado pelo `dedup` gera a linha
+  `debug` `runtime.reaction_duplicate_skipped`. O audit traz um registro por entrega, com
+  `meta: { kind: 'reaction', attempts }` e a identidade do evento, sem o payload.
+- **Encadeamento:** `emits` entra no `bindReaction`, como no `bindAction`. Dentro da reaction,
+  `ctx.emit` publica só os eventos listados; os demais continuam descartados com o aviso
+  `runtime.reaction_emit_ignored`, como antes. O evento publicado herda `actor`, `tenant` e `source`
+  e ganha `cause: { reaction, eventId, eventType, depth }`. A cadeia para em
+  `config.maxReactionDepth` saltos (padrão 5) com o erro `runtime.reaction_chain_too_deep`, que em
+  `emitMode: 'strict'` também interrompe a reaction. `opus introspect` liga o `emits` de uma
+  reaction às reactions que escutam o evento.
+
+### Auditoria
+
+Um sink que lança de forma síncrona, em vez de rejeitar, passa a seguir o `auditMode` como os demais:
+aviso em `lenient` e `audit.sink.failed` em `strict`. Antes, o erro cru escapava do emissor.
+
+### Schedules
+
+`automatable: true`, que existia no contrato sem efeito, passa a ser o opt-in para que um schedule
+execute a action como o sistema. A execução continua sem usuário (`ctx.user` é `null` e `ctx.can`
+nega tudo), e o novo `isSystemActor(ctx)`, de `@softize/opus/core`, permite aceitar o sistema no
+`authorize`: `(ctx) => isSystemActor(ctx) || ctx.can('caixa:fechar')`. Só o runtime cria essa
+identidade: uma chamada HTTP ou a `runtime.execute` sem usuário continua recebendo
+`auth.unauthenticated`, mesmo com provenance `schedule`. O job em background enfileirado pelo
+schedule leva a identidade no worker pela marca `JobSpec.ctx.system`, que o runtime grava ao
+enfileirar; uma provenance `schedule` informada por quem chama não a concede. O audit registra
+`actor: { id: null, type: 'system' }`.
+
+Migração recomendada, não obrigatória: troque `public: true` e `internal: true` da action agendada
+por `automatable: true`. `public: true` continua funcionando. O harness `runAction` ganha a opção
+`schedule` para testar a action como o sistema.
+
 ## 20.1.0 — 2026-09-26
 
 `Content` ganha um slot de mídia e passa a aceitar a moldura integrada ao header também em regiões

package/bin/lib/gen-manifest.mjs

@@ -52,6 +52,7 @@ function shapeAction(a) {
     permission: a.permission,
     authorize: a.authorize,
     public: a.public,
+    automatable: a.automatable,
     internal: a.internal,
     successStatus: a.successStatus,
     input: a.input,

package/bin/lib/gen-runner.mjs

@@ -50,6 +50,7 @@
  *       invalidates?: string[] | '<function>',
  *       successStatus?: number,
  *       public?: boolean,
+ *       automatable?: boolean,             // aceita execução pelo sistema (ADR 0028)
  *       internal?: boolean,
  *       rateLimit?: { window, max },
  *       confirm?: ConfirmSpec,
@@ -373,6 +374,7 @@ function serializeAction(action, ctx) {
     permission: derivePermission(action),
     authorize: serializeAuthorize(action.authorize),
     public: action.public === true,
+    automatable: action.automatable === true,
     internal: action.internal === true,
     successStatus: action.successStatus,
     input: safeToJsonSchema(action.input, ctx),
@@ -478,6 +480,7 @@ function serializeReaction(reaction) {
     description: nullable(reaction.description),
     tags: Array.isArray(reaction.tags) ? reaction.tags : [],
     handler: "<function>",
+    emits: Array.isArray(reaction.emits) ? reaction.emits : [],
     retry: reaction.retry ?? null,
     timeout: reaction.timeout ?? null,
     concurrency: reaction.concurrency ?? null,

package/bin/lib/introspect.mjs

@@ -54,6 +54,7 @@ export function parseStructure(fileName, sourceText) {
         out.reactions.push({
           name: asString(prop(obj, 'name', sf)),
           on: asStringArray(prop(obj, 'on', sf)),
+          emits: asStringArray(prop(obj, 'emits', sf)),
           line: line(node),
         })
       } else if (fn === 'defineSchedule') {
@@ -90,11 +91,11 @@ export function deriveWiring(model) {
   for (const s of model.schedules) {
     if (s.action) edges.push({ kind: 'schedule', from: s.name, to: s.action, via: s.cron ?? s.every ?? 'tempo' })
   }
-  // evento: action.emits → reaction.on
-  for (const a of model.actions) {
-    for (const ev of a.emits ?? []) {
+  // evento: action.emits → reaction.on, e reaction.emits → reaction.on (cadeia, ADR 0027)
+  for (const emitter of [...model.actions, ...model.reactions]) {
+    for (const ev of emitter.emits ?? []) {
       for (const r of model.reactions) {
-        if ((r.on ?? []).includes(ev)) edges.push({ kind: 'event', from: a.name, to: r.name, via: ev })
+        if ((r.on ?? []).includes(ev)) edges.push({ kind: 'event', from: emitter.name, to: r.name, via: ev })
       }
     }
   }

package/docs/adr/0026-reactions-apply-declared-delivery-policy.md

@@ -0,0 +1,123 @@
+# ADR 0026 — Reactions aplicam a política de entrega declarada
+
+- **Status:** aceita (21.0.0).
+- **Data:** 2026-09-26.
+- **Relaciona-se com:** ADR 0027 (encadeamento por evento).
+
+## Contexto
+
+`ReactionDef` e `ReactionBinding` aceitam `retry`, `timeout`, `dedup` e `concurrency`, e a
+`RuntimeConfig` aceita `dedupCacheTtl` e `maxConcurrentReactions`. Até a 20.0.0 o runtime ignorava
+todos eles: cada evento disparava o handler imediatamente, uma falha virava uma linha de log e nada
+era repetido, limitado ou auditado. As páginas `events.md` e `protocol.md` descreviam o pipeline
+pretendido — dedup, authorize, handler com timeout, audit e retry sob um limite de concorrência —
+e, ao lado, avisavam que nada disso era aplicado.
+
+As forças em tensão:
+
+- **Declaração × efeito.** Um campo aceito pelo tipo e ignorado pelo runtime parece proteger o
+  sistema sem proteger.
+- **Repetição × efeito colateral.** Repetir um handler repete o que ele já fez antes de falhar. Só
+  quem escreve a reaction sabe se o handler é idempotente.
+- **Vazão × ordem e carga.** Rodar todos os eventos ao mesmo tempo maximiza vazão, mas sobrecarrega
+  integrações e banco em rajadas e não preserva ordem nenhuma.
+- **Registro × ruído e vazamento.** Uma reaction que muda estado precisa aparecer na trilha de
+  auditoria, mas o payload do evento já foi auditado — com a redação da action — por quem o emitiu.
+
+## Decisão
+
+O runtime aplica a política declarada em cada entrega de evento a uma reaction, nesta ordem:
+
+1. **Dedup.** Com `dedup(event)` declarado, a chave calculada ocupa uma posição por reaction desde a
+   chegada do evento. Outro evento com a mesma chave é descartado enquanto a entrega anterior está
+   na fila ou em andamento, e durante `config.dedupCacheTtl` milissegundos depois de ela concluir com
+   sucesso. Se a entrega falhar em definitivo, a chave é liberada, para que uma nova entrega do mesmo
+   evento possa tentar de novo. O descarte gera uma linha `debug` com o código
+   `runtime.reaction_duplicate_skipped` e não gera audit. Para limitar a memória, cada reaction
+   guarda no máximo `config.dedupCacheMaxEntries` chaves concluídas (padrão 10.000); acima disso, a
+   mais antiga sai antes do TTL. As chaves em andamento não entram no teto.
+2. **Concorrência.** Cada tentativa espera uma vaga da reaction (`concurrency`, padrão 1, como o
+   protocolo já declarava) e uma vaga global (`config.maxConcurrentReactions`, padrão 10), em ordem
+   de chegada. As vagas são liberadas ao fim de cada tentativa e não ficam presas durante a espera
+   entre tentativas.
+3. **Autorização.** `authorize(ctx, event)` roda uma vez, antes da primeira tentativa. `false`
+   descarta o evento sem erro e sem audit, como antes.
+4. **Handler com timeout.** Com `timeout` declarado, o runtime aborta `ctx.signal` quando o prazo
+   vence e encerra a tentativa com `runtime.reaction_timeout`. A vaga é liberada no timeout; um
+   handler que ignora o sinal pode continuar executando em segundo plano.
+5. **Retry.** Sem `retry` declarado, o handler roda uma vez. Com `retry`, `attempts` é o total de
+   execuções, como em `background.retry`. O backoff `fixed` espera `delayMs`; o `exponential` espera
+   `initialMs × multiplier^(n−1)` (multiplier padrão 2), limitado por `maxMs`; sem `backoff`, a nova
+   tentativa começa em seguida. Exceções comuns e `runtime.reaction_timeout` são repetidas. Um
+   `ActionError` segue o próprio `retriable`, cujo padrão vem da categoria (`errors.ts`): só
+   `rate_limit` e `dependency` repetem; `internal` e as demais categorias encerram as tentativas.
+   Quem quer repetir outro erro declara `retriable: true` no `error()`. Cada tentativa que falha e
+   será repetida gera um aviso `runtime.reaction_retry`.
+6. **Audit.** Cada entrega que chegou ao handler, ou que falhou antes dele, gera um único
+   `AuditRecord`: `action` recebe o nome da reaction, `provenance` é a da reaction, `meta` traz
+   `{ kind: 'reaction', attempts }` e `input` traz só a identidade do evento
+   (`{ event: { id, type, source } }`), nunca o payload. A falha definitiva continua gerando a linha
+   `reaction failed` no log, agora com o número de tentativas.
+
+`config.defaultRetry` continua valendo apenas para jobs em background. As políticas valem por
+processo, em memória: com vários processos consumindo o mesmo barramento, cada um mantém o próprio
+dedup e os próprios limites. Valores inválidos (`attempts`, `concurrency` ou `maxConcurrentReactions`
+ou `dedupCacheMaxEntries` fora dos inteiros positivos, `timeout` não positivo, `dedupCacheTtl`
+negativo) interrompem o
+registro ou a criação do runtime com `runtime.invalid_reaction_policy` ou `runtime.invalid_config`.
+
+O `ReactionContext` ganha o campo opcional `signal?: AbortSignal`. O runtime sempre o preenche; o
+campo é opcional para não quebrar quem monta o contexto à mão em testes.
+
+## Consequências
+
+- Uma reaction sem `concurrency` passa a processar um evento por vez. Rajadas ficam em fila na
+  memória do processo, e a ordem de chegada é preservada para a mesma reaction. Um handler que
+  trava sem `timeout` segura a única vaga e para a reaction inteira: os eventos seguintes esperam
+  na fila até o processo reiniciar. Por isso a documentação recomenda declarar `timeout` em toda
+  reaction que depende de algo externo.
+- O limite global de 10 execuções simultâneas passa a valer. Quem precisa de mais vazão aumenta
+  `maxConcurrentReactions` ou `concurrency` da reaction.
+- Os sinks de audit passam a receber registros de reactions, reconhecíveis por
+  `provenance.kind === 'reaction'` com `meta.kind === 'reaction'`. `actionKind` fica ausente.
+- Uma reaction com `retry` precisa de handler idempotente: a documentação diz isso ao lado do
+  exemplo, e `dedup` protege contra a entrega duplicada do mesmo evento, não contra a repetição do
+  próprio handler.
+- Nada muda para quem não declara política, exceto concorrência, limite global e audit.
+
+## Alternativas descartadas
+
+### Manter as políticas ignoradas e documentadas como limite
+
+Custo zero. Foi descartada porque a declaração continua enganando quem lê o contrato e porque o
+protocolo aprovado descreve o pipeline como garantia do core.
+
+### Aplicar `config.defaultRetry` a toda reaction
+
+Daria resiliência sem declaração. Foi descartada porque repetiria três vezes, por padrão, handlers
+escritos sem idempotência, que até a 20.0.0 rodavam uma vez.
+
+### Concorrência ilimitada por reaction, limitada só pelo teto global
+
+Preservaria a vazão anterior. Foi descartada porque o protocolo já declarava padrão 1 e porque uma
+integração externa raramente aceita rajadas sem limite. Quem precisa de paralelismo o declara.
+
+### Auditar cada tentativa ou incluir o payload do evento
+
+Um registro por tentativa multiplicaria o ruído; a sequência de tentativas já aparece no log. O
+payload já está no audit da action que emitiu, com a redação dela; copiá-lo para a reaction
+contornaria essa redação.
+
+### Delegar retry e concorrência ao adapter de eventos
+
+Seria a implementação preferencial com barramentos duráveis. Fica para quando existir um driver
+distribuído: o único driver atual, `mitt`, não tem essas capacidades, e o fallback em memória é o
+que o protocolo prometia.
+
+## Verificação
+
+`tests/core/reaction-policies.test.ts` exercita, pela fronteira do runtime, com relógio falso:
+backoff fixo e exponencial com limite, parada em erro não repetível, timeout com sinal abortado,
+dedup dentro e fora do TTL, teto de chaves, liberação da chave após falha, rejeição tratada quando
+dedup e audit falham juntos, concorrência por reaction e global, validação dos valores e o registro
+de audit de sucesso e de falha.

package/docs/adr/0027-reactions-publish-declared-events-with-bounded-chains.md

@@ -0,0 +1,96 @@
+# ADR 0027 — Reactions publicam os eventos que declaram, em cadeia limitada
+
+- **Status:** aceita (21.0.0).
+- **Data:** 2026-09-26.
+- **Relaciona-se com:** ADR 0026 (política de entrega das reactions).
+
+## Contexto
+
+O `protocol.md` descreve o pipeline de uma reaction a partir de um evento “publicado externamente
+ou por `ctx.emit` interno”, o que pressupõe encadeamento. Até a 20.0.0, porém, `ctx.emit` dentro de
+uma reaction descartava o evento; fora de produção, o runtime registrava o aviso
+`runtime.reaction_emit_ignored` e recomendava emitir o fato na action de origem. Isso obriga a
+action a conhecer consequências que pertencem a outra reaction: por exemplo, a reaction que
+sincroniza um lead com o CRM externo não consegue anunciar `crm.lead.synced` para quem depende da
+sincronização.
+
+As forças em tensão:
+
+- **Composição × laço.** Permitir que reactions publiquem cria cadeias úteis, mas também ciclos: uma
+  reaction em `*` que emite recebe o próprio evento, e duas reactions podem se alimentar
+  mutuamente. Em memória, um ciclo consome CPU e fila até derrubar o processo.
+- **Declaração × conveniência.** Nas actions, `emits` é informativo: um evento fora da lista é
+  publicado com aviso. Reactions nunca publicaram; qualquer publicação é comportamento novo.
+- **Rastreabilidade.** Quem lê um evento encadeado precisa saber qual reaction o publicou, a partir
+  de qual evento e a que distância da action de origem.
+
+## Decisão
+
+1. **Publicação exige declaração.** `emits?: string[]` passa a existir no binding da reaction, como
+   no binding da action. `ctx.emit` dentro de uma reaction publica somente eventos listados em
+   `emits`. Qualquer outro evento, inclusive de reactions sem `emits`, continua descartado, e o
+   aviso `runtime.reaction_emit_ignored` permanece, agora controlado por
+   `config.warnUndeclaredEmits` (ativo por padrão fora de produção), o mesmo interruptor do aviso de
+   evento não declarado das actions. Reactions existentes mantêm exatamente o comportamento anterior.
+2. **O evento encadeado herda a origem e registra a causa.** O runtime preenche `id`, `timestamp`,
+   `trace` (o span da reaction) e `meta`. `actor`, `tenant` e `source` vêm do evento recebido:
+   `source` continua apontando para a action que iniciou a cadeia, e `provenance.sourceActionId` das
+   reactions seguintes continua igual ao `id` do audit dessa action. O campo opcional novo
+   `DomainEvent.cause` diz `{ reaction, eventId, eventType, depth }`: a reaction que publicou, o
+   evento que ela processava e a profundidade na cadeia. Evento emitido por action não tem `cause`
+   e está na profundidade 0.
+3. **A cadeia tem profundidade máxima.** `config.maxReactionDepth` (padrão 5) limita quantos saltos
+   de reaction uma cadeia pode dar. Um `ctx.emit` que produziria um evento acima do limite não
+   publica e registra o erro `runtime.reaction_chain_too_deep` no log, em qualquer ambiente, com a
+   cadeia observada. Com `emitMode: 'strict'`, o mesmo código interrompe a reaction, como
+   `emit.failed` faz com uma falha de publicação.
+4. **O resto do `ctx.emit` segue as actions.** Uma falha de `publish` vira aviso em `lenient` e
+   interrompe a reaction com `emit.failed` em `strict`. Um evento encadeado é entregue às reactions
+   inscritas com a mesma política de entrega (ADR 0026), inclusive à própria reaction que o publicou.
+
+## Consequências
+
+- Uma reaction pode anunciar um fato novo sem que a action de origem o conheça, e o manifest
+  projeta o `emits` da reaction; `opus introspect` passa a ligar esse `emits` às reactions que o
+  escutam.
+- Um ciclo não derruba o processo: ele para na profundidade 5, com um erro no log que nomeia a
+  reaction e o evento. Com fan-out *f*, o pior caso é da ordem de *f*⁵ eventos por evento de origem.
+- Recursão legítima e limitada (por exemplo, percorrer uma árvore rasa) continua possível.
+- Reactions ficam mais estritas que actions: um evento fora de `emits` é descartado, não publicado.
+  A diferença existe porque reactions nunca publicaram e porque a lista declarada é o que torna a
+  cadeia visível no manifest.
+- `DomainEvent` ganha um campo opcional. Barramentos que serializam o evento inteiro o transportam
+  sem mudança; um driver que monta o evento campo a campo precisa copiá-lo para o limite valer entre
+  processos.
+
+## Alternativas descartadas
+
+### Manter o descarte
+
+Não cria risco de laço. Foi descartada porque obriga a action a emitir eventos que descrevem
+consequências de outras reactions, e porque o protocolo já descrevia o encadeamento.
+
+### Publicar qualquer evento, com aviso quando não declarado
+
+Espelharia as actions. Foi descartada porque mudaria em silêncio o comportamento de reactions
+existentes que hoje chamam `ctx.emit` sem efeito, e porque um evento não declarado não aparece no
+manifest, que é onde uma cadeia pode ser revisada.
+
+### Detectar ciclos pela cadeia de causa
+
+Recusaria o evento quando a mesma reaction já aparece na cadeia. Foi descartada porque bloqueia
+recursão legítima, exige transportar a cadeia inteira em cada evento e não limita cadeias longas
+sem ciclo. A profundidade resolve os dois casos com um número.
+
+### Detectar ciclos no grafo declarado durante o `start()`
+
+Útil como diagnóstico, mas insuficiente: padrões como `*`, barramentos externos e reactions de
+outros processos ficam fora do grafo. Pode ser acrescentada depois como aviso do `opus check`.
+
+## Verificação
+
+`tests/core/reaction-policies.test.ts` confere, pela fronteira do runtime: publicação de evento
+declarado com `cause`, `source`, `actor` e `tenant` corretos; descarte e aviso de evento não
+declarado e de reaction sem `emits`; silêncio do aviso com `warnUndeclaredEmits: false`; parada de
+um laço na profundidade configurada com o erro `runtime.reaction_chain_too_deep`; e interrupção da
+reaction no modo `strict`.

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/ownership-vs-shadcn-lock.md

@@ -16,6 +16,11 @@
    tem opinião.
 4. Com o tempo, a biblioteca inteira converge pra "ours" naturalmente, pelo uso — sem
    big-bang, sem cerimônia de virada.
+5. **O ledger acompanha o ejetado.** Editar um componente `ejected` continua livre, mas a
+   edição atualiza no mesmo commit o `localHash` e, quando muda o comportamento, o `delta`
+   do `registry.lock.json`. O `lock.test` confere o hash dos ejetados com esse propósito: não
+   impede a edição, impede que o registro de proveniência derive em silêncio (set/2026, depois
+   de doze ejetados ficarem com hash desatualizado sem nenhum gate perceber).
 
 ## Princípio irmão: sobrescrita sancionada