@softize/opus 19.0.0 → 20.1.0

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
@@ -231,6 +244,11 @@ seccionado com a primeira linha apagada.
 Pela mesma razão, a regra que suprime o divisor entre um header e um rodapé adjacentes precisa
 vencer a que o cria — não basta vir depois dela na folha, porque a ordem das variantes não é nossa.
 
+**O recuo inferior da última região no layout contínuo segue a mesma lógica** (20.0.0). Ele vem de
+`[&:last-child]:pb-*`, e um `pb-0` do consumidor não o desliga quando a região é a última da
+superfície: para mudar esse respiro, a superfície troca de layout. Quem precisar mesmo sobrescrever
+escreve a mesma variante (`[&:last-child]:pb-*`), que o merge reconhece como substituta.
+
 ## Consequências
 
 - Uma mudança de espaçamento, divisor ou escala passa a ter um lugar só; hoje tem seis.

package/docs/adr/0024-fill-height-propagates-by-context.md

@@ -0,0 +1,118 @@
+# ADR 0024 — A ocupação de altura se propaga por contexto
+
+- **Status:** aceita.
+- **Data:** 2026-09-25.
+- **Complementa:** ADRs 0017 e 0023.
+
+## Contexto
+
+`Page layout="fill"` limita a página à altura do shell, e `ActionList layout="fill"` ocupa a altura
+disponível e rola somente os resultados. As duas metades já existiam desde a 18.3.0, mas não se
+encontravam sozinhas: a altura só chega à lista se cada elemento entre a página e ela for uma coluna
+flexível com `min-h-0`. `PageBody`, `Content` e `ContentBody` não faziam isso.
+
+O efeito era mensurável no código e na documentação:
+
+- a página da `ActionList` ensinava a escrever `flex min-h-0 flex-1 flex-col` em `PageBody`,
+  `Content` e `ContentBody` para o `fill` funcionar;
+- a `Presentation` de lista em `layout="fill"` envolvia o corpo em `Content` e `ContentBody` sem essa
+  cadeia e não repassava `layout` à lista — o `fill` declarado nunca chegava a ela;
+- quando uma classe faltava, a lista crescia com o conteúdo e o `fill` se comportava como `flow`,
+  sem erro nem aviso.
+
+As forças em tensão:
+
+- **Automação × previsibilidade.** A cadeia é mecânica e o consumidor erra ao montá-la à mão; mas
+  uma página `fill` também hospeda seções irmãs, cards e diálogos que não devem virar colunas
+  flexíveis por acidente.
+- **Contexto React × DOM.** O contexto atravessa qualquer componente, inclusive portais e
+  contêineres que não repassam altura; a altura só atravessa o DOM elemento a elemento.
+- **Default × explícito.** Uma lista dentro da cadeia quase sempre quer `fill`; uma lista em uma
+  seção secundária da mesma página quer `flow`.
+
+## Decisão
+
+### 1. A raiz publica, os elos republicam, a folha se registra
+
+- **Raiz:** `Page layout="fill"` publica a cadeia. `Page layout="flow"` a interrompe. A
+  `Presentation` em página herda o comportamento da `Page` que monta.
+- **Elos canônicos:** `PageBody`, `Content`, `ContentBody` e o corpo da `Presentation` leem a
+  cadeia e a republicam para os filhos. Na cadeia, carregam `data-fill="false"`.
+- **Folha:** a `ActionList`. Sem `layout`, ela assume `fill` quando o elemento pai no DOM é um elo
+  (`data-fill`) e se registra na cadeia. Com `layout="fill"` explícito, registra-se mesmo sob um
+  contêiner próprio; com `layout="flow"` explícito, nunca se registra.
+
+### 2. Só o caminho até a folha vira coluna flexível
+
+Um elo aplica `flex min-h-0 flex-1 flex-col` e passa a `data-fill="true"` somente quando uma folha
+se registrou abaixo dele. Seções irmãs sem lista mantêm a altura do próprio conteúdo, e uma página
+`fill` sem lista renderiza exatamente como antes. O registro acontece em `useLayoutEffect`, antes
+da primeira pintura.
+
+### 3. Superfícies com anatomia própria interrompem a cadeia
+
+`Card`, `Dialog`, `Drawer` e `Pane` interrompem a propagação no provider de layout que já
+compartilham (ADR 0023). A altura do corpo delas é decisão delas, inclusive quando um portal as
+renderiza dentro de uma página `fill`. A própria `ActionList` também interrompe a cadeia para o que
+ela hospeda. Em `Presentation`, o `fill` continua valendo apenas para a superfície `page`.
+
+### 4. O mecanismo é interno
+
+O contexto e os hooks vivem em um módulo interno, fora da API pública. Um contêiner próprio entre o
+elo e a lista não é detectado como elo: quem o escreve declara `layout="fill"` na lista e dá ao
+contêiner a coluna flexível. Novos elos ou folhas entram no SDK, com teste, e não no consumidor.
+
+## Consequências
+
+- `Page layout="fill"` › `PageBody` › `Content` › `ContentBody` › `ActionList` funciona sem classes
+  no consumidor, e a `Presentation` de lista em `fill` passa a entregar a rolagem interna prometida.
+- Classes que o consumidor já escrevia para montar a cadeia continuam funcionando e podem ser
+  removidas: o `className` é mesclado por último e repete as mesmas classes.
+- Uma `ActionList` sem `layout`, filha direta de um elo em uma página `fill`, passa a ocupar a altura.
+  Quem queria a lista crescendo com a página declara `layout="flow"`.
+- A primeira renderização de uma cadeia com folha faz uma passada extra de layout effect. No
+  servidor, a cadeia só se forma na hidratação.
+- `Tabs` e outros contêineres intermediários não são elos, em qualquer ponto do caminho. A lista só
+  confere o pai imediato: com um contêiner próprio entre dois elos (por exemplo, um `div` entre
+  `PageBody` e `Content`), ela ainda se registra e os elos viram coluna flexível, mas a altura não
+  atravessa o contêiner e a lista se comporta como `flow`. Quem compõe assim dá ao contêiner a
+  coluna flexível, como antes.
+- O elo ativo vira coluna flexível com `align-items: stretch`, que a lista precisa. Os demais filhos
+  de cada elo ativo também são afetados: um botão inline se estica à largura do elo e margens
+  verticais deixam de colapsar. Para um irmão manter a largura do conteúdo, dê a ele `self-start`
+  ou envolva-o em um contêiner próprio.
+- `Dialog` em `mode="alert"` também interrompe a cadeia, como os demais modos.
+
+## Alternativas descartadas
+
+### Manter a cadeia no consumidor
+
+Não custa nada ao SDK. Foi descartada porque é o estado que produziu a documentação ensinando
+classes de correção e a `Presentation` com `fill` que não chegava à lista.
+
+### Aplicar a coluna flexível em todo elo dentro de `fill`
+
+Mais simples: bastaria ler o contexto. Foi descartada porque duas seções irmãs com `flex-1` dividem
+a altura ao meio e o conteúdo de uma transborda sobre a outra, e porque `flex-col` estica filhos
+inline, como botões, que antes tinham a largura do conteúdo.
+
+### Detectar a folha só por CSS (`:has`)
+
+Evitaria o registro em React. Foi descartada porque `:has` enxerga qualquer descendente no DOM,
+inclusive listas dentro de cards e contêineres que não repassam a altura, e porque a decisão da
+lista — `fill` ou `flow` — ainda precisaria do contexto.
+
+### Expor o contexto na API pública
+
+Deixaria o consumidor criar elos próprios. Foi adiada: sem um caso real além de `ActionList`, o
+contrato público seria especulativo.
+
+## Verificação
+
+- `tests/ui/fill-region.test.tsx` renderiza a cadeia `Page fill` › `PageBody` › `Content` ›
+  `ContentBody` › `ActionList` e confere atributo e classes de cada nível; cobre seções irmãs,
+  página `fill` sem lista, página `flow`, `layout="flow"` explícito, contêiner próprio com e sem
+  `fill` explícito, a interrupção por `Card` e a interrupção pela própria lista.
+- `tests/ui/presentation.test.tsx` confere a `Presentation` de lista em `fill`, dentro e fora de
+  `PageShell`, e a lista em `flow` quando a `Presentation` é `flow`.
+- A rolagem real é conferida em navegador: a happy-dom não calcula layout.

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/data-products.md

@@ -10,7 +10,10 @@ Ele não é uma query, tabela ou view: essas são implementações possíveis. A
 recorte e autorização continua sendo cada Action.
 
 ```ts
-import { defineDataProduct, defineDomain } from '@softize/opus'
+import { defineDataProduct, defineDomain } from '@softize/opus/core'
+import { LeadEntity } from './entity.ts'          // defineEntity({ name: 'lead', … })
+import { leadList } from './actions/list.ts'      // action 'lead.list'
+import { leadFunnel } from './actions/funnel.ts'  // action 'lead.funnel'
 
 export const salesLeads = defineDataProduct({
   id: 'sales.leads',
@@ -22,24 +25,27 @@ export const salesLeads = defineDataProduct({
   classification: 'internal',
   nature: 'real',
   sources: [{ id: 'followize', label: 'Followize' }],
-  entities: ['Lead'],
+  entities: ['lead'],
   access: {
     permissionContexts: ['sales'],
     organizationalScopes: ['unit', 'team'],
   },
-  interfaces: ['sale.list', 'sales.performance'],
+  interfaces: ['lead.list', 'lead.funnel'],
 })
 
-export const salesDomain = defineDomain({
-  name: 'sales',
-  entities: { Lead },
-  actions: { saleList, salesPerformance },
+export const leadDomain = defineDomain({
+  name: 'lead',
+  entities: { LeadEntity },
+  actions: { leadList, leadFunnel },
   dataProducts: { salesLeads },
 })
 ```
 
-`interfaces` e `entities` usam os nomes declarados, não nomes de arquivo ou tabela. O registro do
-domínio e `opus check` detectam relações inexistentes. `sources` identifica sistemas ou conjuntos
+`interfaces` e `entities` usam os nomes declarados — o `name` da action e o `name` de
+`defineEntity` —, não a chave do objeto, o nome do arquivo ou da tabela. O registro do domínio e
+`opus check` detectam relações inexistentes: aqui, `entities: ['LeadEntity']` ou `['Lead']` seriam
+recusados, porque a entidade se declara como `lead`. As actions seguem o prefixo do domínio
+(`lead.*`), como qualquer action registrada nele. `sources` identifica sistemas ou conjuntos
 upstream; uma Fonte não precisa ser uma Entity Opus.
 
 ## Acesso e segurança

package/docs/protocol.md

@@ -1606,7 +1606,6 @@ defineReaction({
   
   handler: async (ctx, event) => {
     await syncToSalesforce(event.data.leadId)
-    await ctx.emit('hub.lead.synced', { leadId: event.data.leadId })
   },
 })
 
@@ -1629,7 +1628,7 @@ type ReactionContext = {
   user:     User | null              // ator que disparou o evento (pode ser system)
   tenantId: string | null
   db:       unknown                  // mesmo data adapter
-  emit:     EmitFn                   // reaction pode emitir novos eventos (chain)
+  emit:     EmitFn                   // descarta o evento sem publicar (sem encadeamento)
   log:      LoggerAdapter            // logger pre-bound com contexto da reaction
   storage:  StorageAdapter | null    // storage de arquivos (experimental)
   provenance: Provenance             // { kind: 'reaction', … }
@@ -1638,7 +1637,7 @@ type ReactionContext = {
 }
 ```
 
-Reaction pode emitir eventos novos via `ctx.emit` — habilita workflows declarativos em cadeia (`lead.created` → reaction → `lead.onboarded` → outra reaction → ...).
+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`.
 
 ### Setup unificado
 
@@ -1690,7 +1689,7 @@ para cada reaction:
    ↓ (a) dedup check (se declarado)
    ↓ (b) authorize (se declarado)
    ↓ (c) handler executa (com timeout)
-   ↓ (d) handler emite eventos (opcional, via ctx.emit)
+   ↓ (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
 ```

package/docs/releasing.md

@@ -60,7 +60,7 @@ pra testar publicação seria a guarda atrapalhando quem está experimentando.
 
 **Gate de qualidade**: depois do bump e da materialização, mas antes de publicar, roda
 `pnpm typecheck` + `pnpm test` + `pnpm copy:check` + `base copy check` e **aborta a release
-se qualquer um falhar**. O Opus declara `@softize/base ^2.3.0` em `dependencies`, pois usa
+se qualquer um falhar**. O Opus declara `@softize/base ^2.4.0` em `dependencies`, pois usa
 suas APIs públicas de filesystem em runtime, e materializa os artefatos Base no próprio repo;
 a release não baixa uma política ad hoc. Como o
 Opus **ship source** (`.ts`, sem build), essa é a última barreira antes do tarball — sem ela,
@@ -74,7 +74,7 @@ não é bloqueada por cobertura abaixo de 100%; a cobertura é acompanhada com `
 **Smoke do esqueleto**: depois do bump e antes do publish, o `release.sh` gera um app com
 `opus create`, instala o **tarball exato** que vai ser publicado e roda os gates dele
 (typecheck · test · `opus check` · `opus copy --check` · `base copy check` · manifest ·
-build). O template exige `@softize/base ^2.3.0`; publique a Base compatível antes do Opus.
+build). O template exige `@softize/base ^2.4.0`; publique a Base compatível antes do Opus.
 O `minimumReleaseAgeExclude` do template inclui os dois pacotes, e o smoke executa os
 fragmentos de pre-push para provar que o layout pnpm instalado resolve ambos os CLIs.
 É o que pega o que typecheck+test não

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softize/opus",
-  "version": "19.0.0",
+  "version": "20.1.0",
   "description": "End-to-end action protocol for TypeScript. Single package with subpath exports (core + adapters).",
   "license": "MIT",
   "type": "module",
@@ -247,7 +247,7 @@
     "@radix-ui/react-slot": "^1.1.1",
     "@radix-ui/react-tabs": "^1.1.2",
     "@radix-ui/react-tooltip": "^1.1.6",
-    "@softize/base": "^2.3.0",
+    "@softize/base": "^2.4.0",
     "@tailwindcss/typography": "^0.5.20",
     "@types/markdown-it": "^14.1.2",
     "class-variance-authority": "^0.7.1",

package/registry/skills/create-opus-action/scripts/scaffold.mjs

@@ -2,7 +2,8 @@
 
 const KINDS = new Set(['simple', 'form', 'list', 'view'])
 const cap = (value) => value.charAt(0).toUpperCase() + value.slice(1)
-const constant = (resource, verb) => resource + verb.split('-').map(cap).join('')
+const camel = (value) => value.split('-').map((part, index) => (index === 0 ? part : cap(part))).join('')
+const constant = (resource, verb) => camel(`${resource}-${verb}`)
 
 function contractBody({ resource, verb, kind }) {
   const name = `${resource}.${verb}`

package/registry/templates/app/package.json

@@ -30,7 +30,7 @@
     "zod": "^3.24.0"
   },
   "devDependencies": {
-    "@softize/base": "^2.3.0",
+    "@softize/base": "^2.4.0",
     "@tailwindcss/vite": "^4.1.0",
     "@types/node": "^22.0.0",
     "@types/react": "^19.0.0",

package/src/core/runtime.ts

@@ -413,9 +413,35 @@ export class Runtime {
         })
       }
       this.actions.set(action.name, action)
+      if (this.config.dev) this.warnIgnoredExecutionFields(action)
     }
   }
 
+  /**
+   * `emits` e `background` pertencem ao binding de qualquer kind pelo tipo, mas o runtime e o
+   * manifest só os aplicam em `simple` e `form`. Restringir o tipo quebraria bindings
+   * existentes; o aviso em desenvolvimento evita que a declaração pareça ter efeito.
+   */
+  private warnIgnoredExecutionFields(action: ActionDef): void {
+    if (action.kind !== 'list' && action.kind !== 'view') return
+    const declared = action as { emits?: unknown; background?: unknown }
+    const fields = (['emits', 'background'] as const).filter((field) => declared[field] !== undefined)
+    if (fields.length === 0) return
+    const list = fields.map((field) => `\`${field}\``).join(' e ')
+    const effects = fields.map((field) =>
+      field === 'background'
+        ? 'Sem fila, a action executa na própria requisição.'
+        : 'Os eventos declarados não entram no manifest nem na conferência do que o handler emite.',
+    )
+    this.log.warn(
+      `A action "${action.name}" é do kind "${action.kind}" e declara ${list}, que o runtime só ` +
+        `aplica em actions simple e form. ${effects.join(' ')} Remova ${list} da declaração da ` +
+        'action, no `bindAction` ou no `defineAction`; se a operação precisa de fila ou de ' +
+        'eventos declarados, use uma action simple ou form.',
+      { code: 'runtime.action_field_ignored', action: action.name, kind: action.kind, fields },
+    )
+  }
+
   private registerReactions(reactions: Array<ReactionDef<any>>): void {
     for (const reaction of reactions) {
       if (this.reactions.has(reaction.name)) {
@@ -455,6 +481,12 @@ export class Runtime {
       })
     }
 
+    // Antes de inicializar adapters: é uma checagem do registro, e falhar aqui não deixa
+    // conexão aberta para trás. Sem scheduler, a checagem não roda porque nenhum schedule
+    // executaria: os adapters inicializam e o start falha depois, com
+    // `runtime.eventbus_required` se também faltar event bus, senão `runtime.scheduler_required`.
+    if (this.scheduler !== undefined) this.assertScheduledActionsExist()
+
     for (const adapter of this.allAdapters()) {
       if (adapter.init !== undefined) await adapter.init(this)
       if (adapter.dispose !== undefined) {
@@ -1203,6 +1235,35 @@ export class Runtime {
     }
   }
 
+  /**
+   * Um schedule com nome de action errado dispararia em silêncio para sempre. Schedules com
+   * `enabled: false` ficam de fora: não são registrados e podem apontar para uma action que
+   * ainda não existe neste ambiente.
+   */
+  private assertScheduledActionsExist(): void {
+    const missing = [...this.schedules.values()].filter(
+      (schedule) => schedule.enabled !== false && !this.actions.has(schedule.action),
+    )
+    if (missing.length === 0) return
+    const list = missing
+      .map((schedule) => `"${schedule.name}" → "${schedule.action}"`)
+      .join(', ')
+    throw error({
+      code: 'runtime.schedule_action_not_found',
+      category: 'internal',
+      message:
+        `O runtime não iniciou porque ${
+          missing.length === 1
+            ? 'um schedule aponta para uma action não registrada'
+            : `${missing.length} schedules apontam para actions não registradas`
+        }: ${list}. Corrija o nome em \`action\` ou registre a action no mesmo runtime; para ` +
+        'manter o schedule sem executar, declare `enabled: false`.',
+      meta: {
+        schedules: missing.map((schedule) => ({ schedule: schedule.name, action: schedule.action })),
+      },
+    })
+  }
+
   private registerSchedule(schedule: ScheduleDef): void {
     if (schedule.enabled === false) {
       this.log.info('schedule disabled', { schedule: schedule.name })
@@ -1221,12 +1282,45 @@ export class Runtime {
       typeof schedule.input === 'function'
         ? await (schedule.input as () => unknown | Promise<unknown>)()
         : (schedule.input ?? {})
-    await this.execute(schedule.action, input, {
+    const result = await this.execute(schedule.action, input, {
       user: null,
       tenantId: null,
       can: () => false,
       provenance: { kind: 'schedule', scheduleName: schedule.name },
     })
+    if (result.ok) return
+    // Ninguém espera o resultado de um disparo: sem este registro, a falha só existiria no
+    // audit da action. Action inexistente não chega aqui, porque o start() recusa o schedule.
+    this.log.error(
+      `O schedule "${schedule.name}" não concluiu a action "${schedule.action}" (${result.error.code}). ` +
+        'O agendamento continua ativo e o próximo disparo executa a action de novo. Confira a ' +
+        'mensagem e o audit da action; `auth.unauthenticated` indica que a action agendada precisa ' +
+        'declarar `public: true`.',
+      {
+        schedule: schedule.name,
+        action: schedule.action,
+        code: result.error.code,
+        message: result.error.message,
+        actionId: result.meta.actionId,
+        ...(result.error.cause !== undefined ? { cause: result.error.cause } : {}),
+      },
+    )
+  }
+
+  /**
+   * `ctx.emit` de reaction não publica: encadear reactions por evento ainda não é suportado.
+   * Fora de produção, o descarte vira aviso para que o evento não pareça ter sido entregue.
+   */
+  private buildReactionEmit(reaction: ReactionDef<any>, log: Logger): ReactionContext['emit'] {
+    return async (event) => {
+      if (!this.config.dev) return
+      log.warn(
+        `A reaction "${reaction.name}" chamou ctx.emit('${event}'), mas reactions não publicam ` +
+          'eventos: o evento foi descartado e nenhuma reaction ou integração o recebe. Para ' +
+          'anunciar esse fato, emita-o no handler da action que o produz e declare-o em `emits`.',
+        { code: 'runtime.reaction_emit_ignored', reaction: reaction.name, event },
+      )
+    }
   }
 
   private async runReaction(
@@ -1260,7 +1354,7 @@ export class Runtime {
       tenantId: event.tenant ?? null,
       db: this.data?.contextExtension().db,
       log: reactionLog,
-      emit: noopEmit,
+      emit: this.buildReactionEmit(reaction, reactionLog),
       storage: this.storage ?? null,
       cache: this.cache ?? null,
       // Reação = contexto de sistema; o agente só alcança actions públicas (can nega por
@@ -1411,12 +1505,6 @@ function severityForError(err: any): 'info' | 'warning' | 'error' {
   return 'error'
 }
 
-/**
- * Placeholder pra `ctx.emit` em reactions. Reaction chain (reaction emite
- * eventos novos que disparam outras reactions) entra em v1+.
- */
-const noopEmit: ActionContext['emit'] = async () => undefined
-
 function generateId(): string {
   if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
     return crypto.randomUUID()

package/src/core/types.ts

@@ -255,8 +255,10 @@ export interface User {
 export type CanFn = (permission: string, resource?: unknown) => boolean | Promise<boolean>
 
 /**
- * Função que emite um `DomainEvent`. Disponível em `ActionContext.emit` e
- * `ReactionContext.emit`. Plugada pelo `EventBusAdapter`.
+ * Função que emite um `DomainEvent`. Em `ActionContext.emit`, publica o evento pelo
+ * `EventBusAdapter`. Em `ReactionContext.emit`, descarta o evento sem publicá-lo, porque
+ * reactions ainda não encadeiam outras por evento; com `config.dev` ativo, cada descarte
+ * registra o aviso `runtime.reaction_emit_ignored`.
  */
 export type EmitFn = <T = unknown>(
   event: string,
@@ -293,6 +295,7 @@ export interface ReactionContext {
   tenantId: string | null
   db: unknown
   log: Logger
+  /** Descarta o evento sem publicá-lo: reactions ainda não encadeiam outras. Ver `EmitFn`. */
   emit: EmitFn
   storage: StorageAdapter | null
   cache: CacheAdapter | null