@softize/opus 20.0.0 → 21.0.0

package/CHANGELOG.md

@@ -7,6 +7,147 @@ 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.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
+de leitura. Quem não usa as novas props mantém a mesma aparência: `frameVariant="default"` continua
+sendo o padrão, com a borda contínua em `section` e em `fieldset`. Alguns pontos podem pedir ajuste
+sem interromper a aplicação:
+
+- a `legend` de todo `Content as="fieldset"` passa a envolver o título nos wrappers do header
+  (`legend > span[data-slot=content-heading] > …`): um seletor como
+  `legend > [data-slot=content-title]` deixa de casar; use `legend [data-slot=content-title]`;
+- um `ContentHeader` de fieldset com slot inválido lança outra mensagem: “ContentHeader de fieldset
+  aceita somente ContentMedia e ContentTitle; contador, descrição e ações ficam fora da legenda.”
+  Atualize testes que conferem o texto;
+- com `frameVariant="legend"` dentro de uma superfície com fundo próprio, como um `Card` com `bg-*`
+  ou um `Popover`, declare `--surface-background` com esse fundo na superfície (veja **Cor da
+  superfície**);
+- em `advancedFilters.sectionIcons`, um glifo solto ganha a moldura padrão, e testes que buscavam
+  `[data-slot="content-title-icon"]` devem buscar `[data-slot="content-media"]`.
+
+Em detalhe:
+
+- **Mídia no header.** `ContentHeader` aceita `ContentMedia`, e a forma curta de `Content` ganha
+  `media`. O slot já é a moldura de `IconTile`, com a mesma escala e posição em `section` e em
+  `fieldset`: passe só o glifo e escolha `size`, `context` e `variant` no slot. Se você colocava um
+  `IconTile` dentro de `title`, mova-o para `media`; o slot o adota e herda o que ele declara, sem
+  desenhar moldura dentro de moldura. `media` com `null` ou `false` não desenha nada. Em `fieldset`,
+  a mídia é decorativa e não entra no nome do grupo.
+- **Moldura integrada em `section`.** `frameVariant="legend"` deixa de exigir `as="fieldset"`. Em
+  uma `section`, o título continua sendo um heading no nível declarado, e contador, descrição e
+  ações continuam disponíveis; nenhuma `legend` é emitida. Use `as="fieldset"` só para grupos de
+  campos: a `legend` aceita a mídia e o título, e contador, descrição e ações continuam fora dela
+  (ADR 0025).
+- **Cor da superfície.** Para interromper a borda, o header pinta o título e as ações com a
+  variável `--surface-background`. `Card`, `Dialog` e `Drawer` a declaram com o fundo que pintam,
+  então a linha não reaparece atrás do título quando há um `CardBody`, um `DrawerBody` ou outro
+  wrapper transparente no caminho. Fora delas, vale `--background`.
+- **Filtros avançados.** Os ícones de `advancedFilters.sectionIcons` passam a ocupar o
+  `ContentMedia` de cada seção: um glifo solto ganha a moldura padrão, em vez do ícone esmaecido sem
+  moldura, e um `IconTile` é adotado pelo slot com o que declara. Um ícone `null` não desenha
+  moldura.
+
+A página de `Content` mostra a mídia, os dois acabamentos da moldura e a declaração de
+`--surface-background`. A ADR 0025 registra que o acabamento da moldura não altera a semântica; a
+ADR 0023 ganha a emenda do slot de mídia de `Content`, e as ADRs 0020 e 0021, emendas que apontam
+para a 0025.
+
 ## 20.0.0 — 2026-09-26
 
 Esta versão corrige componentes que falhavam em acessibilidade ou em layout, leva o `fill` da

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/0020-icon-tiles-are-explicitly-composed.md

@@ -24,6 +24,14 @@ a mesma base visual porque essas variantes já prometem a moldura.
 `IconTile` é somente apresentação. Quando o ícone aciona algo, deve-se usar `Button` com tamanho
 de ícone e nome acessível.
 
+### Emenda de 2026-09-26 — slots de mídia das superfícies
+
+Os slots de mídia da anatomia de superfícies (ADR 0023), como `CardMedia` e `ContentMedia`, não são
+slots genéricos: assim como `ItemMedia variant="icon"`, eles já prometem a moldura, e o consumidor
+passa só o glifo. `ContentMedia` adota um `IconTile` recebido como filho em vez de desenhar uma
+moldura dentro da outra (ADR 0025). Slots genéricos, como `FieldLegend.icon`, continuam como esta
+ADR descreve.
+
 ## Consequências
 
 - A presença da moldura deixa de ser uma regra implícita da legenda.

package/docs/adr/0021-content-carries-structure-and-semantic-element.md

@@ -30,6 +30,13 @@ uma `section`. A escolha de `fieldset` não define o acabamento visual: quando `
 presente, a moldura é contínua por padrão. Os filtros avançados preservam a legenda integrada à
 borda declarando `frameVariant="legend"`.
 
+### Emenda de 2026-09-26 — o acabamento `legend` também vale para `section`
+
+A ADR 0025 estende `frameVariant="legend"` a `Content as="section"`, para que regiões de leitura
+integrem o header à moldura sem declarar semântica de formulário, e permite `ContentMedia` na
+legenda de um `fieldset`. A regra desta ADR se mantém: `as` escolhe o elemento e a semântica, e
+`frameVariant` escolhe só o acabamento. Na legenda, contador, descrição e ações continuam inválidos.
+
 ## Consequências
 
 - A mesma API nomeia e delimita regiões de leitura e grupos de formulário.

package/docs/adr/0023-surfaces-share-one-anatomy-and-two-layouts.md

@@ -143,7 +143,7 @@ anteriores já os delimitaram:
 
 | Slot | Card | Content | Page | Dialog | Drawer | Pane |
 | --- | --- | --- | --- | --- | --- | --- |
-| Media | sim | não | não | sim (`DialogMedia`) | sim | sim |
+| Media | sim | sim (`ContentMedia`) | não | sim (`DialogMedia`) | sim | sim |
 | Title | sim | sim | sim | sim | sim | sim |
 | Description | sim | sim | não (ADR 0014) | não (ADR 0018) | não (ADR 0018) | não |
 | Meta | não | sim (contador) | não (ADR 0009) | não | não | não |
@@ -163,6 +163,19 @@ de um cabeçalho remontam a linha com `span`, incluindo o ícone dentro do texto
 `Content` permanece sem footer: é uma região nomeada dentro de outra superfície, e um rodapé
 pertence à superfície que a hospeda.
 
+#### Emenda de 2026-09-25 — Content também expõe mídia
+
+A aplicação posterior da anatomia à tela do Evento mostrou que regiões de leitura podem precisar
+da mesma identificação visual que um Card sem deixarem de ser `Content`. Sem um slot próprio, a
+documentação e os consumidores voltavam a inserir o ícone dentro de `ContentTitle`, repetindo o
+desvio que motivou esta ADR.
+
+`ContentHeader` passa a aceitar `ContentMedia`, e o shorthand expõe `media`. A mídia usa a mesma
+moldura de `IconTile` das demais famílias e integra o grupo visual do título. Esse contrato vale
+tanto para `section` quanto para `fieldset`: `as` troca o elemento e a semântica, não a apresentação
+de mídia e título. Na `legend`, contador, descrição e ações continuam indisponíveis porque não
+nomeiam o grupo de campos.
+
 ### 7. Título: hierarquia e tamanho são independentes
 
 O nível semântico vem de `level` (`1`–`6`) ou de `asChild`, e nunca do tamanho visual. O tamanho vem

package/docs/adr/0025-content-frame-treatment-does-not-change-semantics.md

@@ -0,0 +1,134 @@
+# ADR 0025 — O acabamento da moldura de Content não altera sua semântica
+
+- **Status:** aceita.
+- **Data:** 2026-09-25.
+- **Complementa:** ADRs 0021 e 0023.
+
+## Contexto
+
+`Content` separa o elemento semântico (`section` ou `fieldset`) da presença da moldura. Porém, o
+acabamento `frameVariant="legend"`, que integra visualmente o título à borda, só está disponível
+quando a raiz é um `fieldset`.
+
+Essa restrição leva regiões somente de leitura a escolherem `fieldset` apenas para obter o
+acabamento visual. É o caso de grupos de detalhes como Cliente e Veículo: eles formam seções
+nomeadas com `DetailGroup`, não conjuntos de controles de formulário. A aparência desejada se
+parece com uma legenda, mas não transforma o título em uma `legend` semântica.
+
+As forças em tensão são:
+
+- preservar `fieldset` e `legend` exclusivamente para grupos de campos relacionados;
+- oferecer a mesma linguagem visual a regiões de leitura;
+- manter título, mídia, descrição, contador e ações compatíveis com a anatomia normal de `Content`;
+- não criar outra família pública apenas para desenhar uma borda interrompida.
+
+## Decisão
+
+`frameVariant="legend"` passa a ser aceito tanto por `Content as="section"` quanto por
+`Content as="fieldset"`. A propriedade escolhe somente o acabamento da moldura; `as` continua
+sendo a única propriedade que determina o elemento e sua semântica.
+
+Em uma `section`, o título permanece um heading no nível declarado, o header continua aceitando
+`ContentMedia`, `ContentMeta`, `ContentDescription` e `ContentActions`, e a borda é visualmente
+interrompida ao redor das regiões do header que a ocupam. Nenhum elemento `legend` é emitido.
+
+Em um `fieldset`, o título continua sendo a `legend` nativa e pode ser precedido pelo mesmo
+`ContentMedia` usado em uma `section`. A mídia é decorativa e acompanha o nome do grupo; contador,
+descrição e ações continuam fora da legenda. `as` altera a semântica, não a apresentação do par
+mídia + título nem o comportamento nativo de formulários.
+
+O nome `legend` descreve o acabamento visual existente e não cria um terceiro valor incompatível
+para o mesmo desenho. A documentação deve apresentar primeiro a escolha semântica e depois o
+acabamento, deixando explícito que uma região de leitura permanece `section`.
+
+Para interromper a linha sem depender da transparência dos wrappers intermediários, Card, Dialog e
+Drawer declaram `--surface-background` com o token que já usam (`--background` ou `--card`). As
+regiões do header que cruzam a borda usam essa cor; quando não houver uma superfície declarada,
+`Content` usa `--background` como fallback. O nome segue o papel da variável, como os demais
+contratos CSS locais, sem prefixo de pacote. Uma superfície com fundo próprio que não seja uma
+dessas três, como um `Card` com `bg-*`, um `Popover` ou um contêiner da aplicação, declara a mesma
+variável com o fundo que pinta.
+
+### Relação com a ADR 0020
+
+A ADR 0020 mantém genéricos os slots de ícone, como `FieldLegend.icon`: o consumidor passa o glifo
+quando quer só o ícone e compõe `IconTile` quando quer a moldura. `ContentMedia` não é um slot
+genérico; é o slot de mídia da anatomia de superfícies (ADR 0023), que já promete a moldura, como
+`CardMedia` e `ItemMedia variant="icon"`. Por isso a mídia de `Content` sempre desenha a moldura, e
+`asChild` continua sendo a saída para uma marca com visual próprio.
+
+Consumidores que já compunham `IconTile` antes deste slot existir não devem ganhar moldura dentro de
+moldura. `ContentMedia` adota um `IconTile` recebido como filho: o slot assume o lugar dele e herda
+`size`, `context`, `variant` e as demais props declaradas nele. `media` com `null` ou `false` é
+tratado como ausência, e nenhuma moldura vazia é desenhada. Os ícones de
+`advancedFilters.sectionIcons` da `ActionList` passam pelo mesmo slot, sem normalização própria.
+
+## Consequências
+
+- Regiões de leitura podem integrar o header à moldura sem declarar semântica de formulário.
+- A composição `Content + DetailGroup` preserva `section`, heading, mídia, descrição, contador e
+  ações.
+- Grupos de campos continuam usando `fieldset` e `legend` quando essa relação existe no conteúdo.
+- Filtros e regiões de leitura usam o mesmo slot, escala e alinhamento para mídia e título.
+- O default permanece `frameVariant="default"`; quem não usa as novas props não muda visualmente.
+- `advancedFilters.sectionIcons` muda: um glifo solto, antes exibido sem moldura, passa a ocupar o
+  `ContentMedia` e ganha a moldura padrão. Um `IconTile` continua com a aparência que declara.
+- A `legend` de todo `Content as="fieldset"` passa a envolver título e mídia nos wrappers do
+  `SurfaceHeader` (`legend > span[data-slot=content-heading] > …`). Seletores que dependiam do
+  título como filho direto da `legend` precisam ser ajustados.
+- O acabamento precisa funcionar sobre as superfícies canônicas sem o consumidor reconstruir a
+  borda ou posicionar o header por classes próprias.
+- Wrappers transparentes entre a superfície e `Content` não deixam a borda aparecer atrás do grupo
+  de heading ou das ações, porque a cor vem da variável declarada pela superfície e não do pai.
+- Superfícies com fundo próprio fora de Card, Dialog e Drawer ficam responsáveis por declarar
+  `--surface-background`; sem isso, a faixa atrás do header usa `--background`.
+
+## Alternativas consideradas
+
+### Usar `fieldset` também para detalhes somente de leitura
+
+Reaproveitaria a implementação atual, mas atribuiria semântica de grupo de formulário a uma lista
+de definições. Foi descartada porque a escolha do elemento passaria a ser governada pela aparência.
+
+### Criar outro componente de painel
+
+Separaria esse desenho de `Content`, mas duplicaria a anatomia de região nomeada e voltaria a exigir
+uma decisão entre estruturas equivalentes. Foi descartada porque `Content` já é responsável pelo
+header, corpo e moldura da região.
+
+### Criar um novo valor visual com o mesmo desenho
+
+Um nome como `notched` evitaria a associação com a `legend`, mas criaria dois valores para o mesmo
+acabamento e uma migração sem ganho observável. Foi descartado porque o contrato já afirma que
+`frameVariant` não altera a semântica.
+
+### Herdar o background do pai imediato
+
+Manteria a implementação restrita a `Content`, mas `background-color: inherit` recebe
+`transparent` quando `DrawerBody`, `CardBody` ou outro wrapper não pinta o próprio fundo. Foi
+descartado porque o acabamento depende da superfície que efetivamente pinta, não do pai estrutural
+mais próximo.
+
+### Redesenhar a borda em segmentos
+
+Evitaria cobrir a linha com uma cor, mas exigiria derivar segmentos antes, entre e depois de título,
+descrição e ações com larguras dinâmicas. Foi descartado porque duplicaria no CSS a anatomia que o
+header já organiza.
+
+## Verificação
+
+- Testes de UI confirmam que `Content as="section"` com `frameVariant="legend"` mantém `section`,
+  heading e todos os slots do header.
+- Testes confirmam que o mesmo acabamento em `fieldset` continua emitindo `legend` e restringindo
+  seus slots.
+- Testes confirmam que o default continua usando a moldura contínua nos dois elementos.
+- Testes confirmam que Card, Dialog e Drawer declaram `--surface-background` e que o grupo de
+  heading e as ações do header usam essa variável, com `--background` como fallback. A herança da
+  variável através de wrappers transparentes é comportamento do CSS, não é provada pela happy-dom e
+  depende de conferência visual no catálogo, onde a página de `Content` a demonstra sobre um `Card`.
+- Testes confirmam que um `IconTile` passado como mídia é adotado pelo slot, que `null` e `false`
+  não desenham mídia e que um glifo solto em `sectionIcons` ganha a moldura.
+- Um teste confirma que `Page layout="fill"` leva a altura até a `ActionList` através de um
+  `Content` com `frameVariant="legend"` (ADR 0024).
+- A documentação demonstra `Content + DetailGroup` no acabamento `legend` sem usar `fieldset` e
+  mantém `Content as="fieldset" + FieldGroup` para grupos de controles.

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