@softize/opus 18.5.0 → 20.0.0

package/src/ui/docs/content/progress.md

@@ -1,18 +1,26 @@
 ## Progresso determinado
 
-Use `Progress` quando a tarefa informar uma porcentagem de conclusão. `value` aceita valores de 0 a
-100 e anima o preenchimento a cada mudança. Sem valor, a barra permanece vazia.
+Use `Progress` quando a tarefa informar quanto já foi concluído. `value` aceita valores de 0 a
+`max`, que por padrão é 100, e anima o preenchimento a cada mudança. Para contar etapas, declare
+`max` com o total: `value={3} max={4}` preenche três quartos da barra. Quando a duração da espera
+não é conhecida, use [`Spinner`](/ui/spinner).
+
+A barra é exposta aos leitores de tela como `progressbar`, com o valor atual, mas o texto ao lado
+dela não a nomeia automaticamente. Ligue o rótulo visível à barra com `aria-labelledby` ou, sem
+rótulo visível, passe `aria-label`.
 
 ```tsx preview col
 <div className="w-full max-w-sm space-y-2">
   <div className="flex items-center justify-between text-sm">
-    <span>opus check</span>
+    <span id="progress-check">opus check</span>
     <span className="text-muted-foreground">65%</span>
   </div>
-  <Progress value={65} />
+  <Progress value={65} aria-labelledby="progress-check" />
 </div>
 ```
 
+Sem `value`, ou com `null`, a barra fica vazia e é exposta como progresso indeterminado.
+
 ## Controlado
 
 Controle `value` externamente quando o progresso acompanhar uma tarefa em andamento. No exemplo,
@@ -20,15 +28,16 @@ cada clique avança uma etapa da sincronização.
 
 ```tsx preview col
 const [step, setStep] = useState(40)
+const labelId = useId()
 const advance = (): void => setStep((prev) => Math.min(prev + 20, 100))
 
 render(
   <div className="w-full max-w-sm space-y-3">
     <div className="flex items-center justify-between text-sm">
-      <span>Sincronizar Empresa X</span>
+      <span id={labelId}>Sincronizar Empresa X</span>
       <span className="text-muted-foreground">{step}%</span>
     </div>
-    <Progress value={step} />
+    <Progress value={step} aria-labelledby={labelId} />
     <Button variant="outline" size="sm" onClick={advance}>
       Avançar etapa
     </Button>
@@ -39,18 +48,19 @@ render(
 ## Altura e contexto
 
 `context` diz o que o andamento comunica — `success` para meta atingida, `warning` ou `danger`
-para atenção — e tinge trilha e preenchimento com a família semântica. `className` compõe sobre o
-padrão para ajustar a altura.
+para atenção — e tinge trilha e preenchimento com a família semântica. A cor reforça o significado,
+mas não o substitui: mantenha o rótulo e o valor legíveis. `className` compõe sobre o padrão para
+ajustar a altura.
 
 ```tsx preview col
 <div className="w-full max-w-sm space-y-4">
   <div className="space-y-1.5">
-    <span className="text-sm">Cobertura de testes</span>
-    <Progress value={92} context="success" className="h-1.5" />
+    <span id="progress-coverage" className="text-sm">Cobertura de testes</span>
+    <Progress value={92} context="success" className="h-1.5" aria-labelledby="progress-coverage" />
   </div>
   <div className="space-y-1.5">
-    <span className="text-sm">Skills cobertas pelo revisor</span>
-    <Progress value={45} context="warning" className="h-3" />
+    <span id="progress-review" className="text-sm">Skills cobertas pelo revisor</span>
+    <Progress value={45} context="warning" className="h-3" aria-labelledby="progress-review" />
   </div>
 </div>
 ```
@@ -59,6 +69,9 @@ padrão para ajustar a altura.
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `value` | `number \| null` | | O progresso de 0 a 100. O preenchimento anima a cada mudança; null/ausente deixa a barra vazia. |
+| `value` | `number \| null` | | O progresso de 0 a `max`. O preenchimento anima a cada mudança; sem valor, a barra fica vazia e indeterminada. |
+| `max` | `number` | `100` | O valor que representa a conclusão. O preenchimento é a fração `value / max`. |
 | `context` | `'neutral' \| 'primary' \| 'info' \| 'success' \| 'warning' \| 'danger'` | `'primary'` | O que o andamento comunica; tinge trilha e preenchimento pela família `--context-*`. |
-| `className` | `string` | | Compõe sobre o padrão — ajuste a altura (h-1.5/h-3). |
+| `aria-label` | `string` | | Nome acessível da barra quando não há rótulo visível. |
+| `aria-labelledby` | `string` | | `id` do rótulo visível que nomeia a barra. |
+| `className` | `string` | | Compõe sobre o padrão — ajuste a altura (`h-1.5`, `h-3`). |

package/src/ui/docs/content/queue.md

@@ -5,7 +5,7 @@ title: Filas
 # Filas
 
 Use uma action em background quando a operação não puder manter a requisição aberta. O
-`QueueAdapter` enfileira o trabalho e devolve um `JobHandle` para acompanhamento pelo cliente.
+`QueueAdapter` enfileira o trabalho e devolve um `JobHandle` para acompanhar o andamento.
 
 ## O contrato
 
@@ -21,18 +21,21 @@ interface JobHandle<T = unknown> {
   jobId: string
   action: string
   status: 'queued' | 'running' | 'done' | 'failed' | 'cancelled'
-  progress?: { percent?: number; message?: string }
+  progress?: { percent?: number; message?: string; data?: unknown }
   data?: T
   error?: ActionError
+  enqueuedAt: string
+  startedAt?: string
+  finishedAt?: string
   attempts: number
   trace?: TraceContext
 }
 ```
 
-`runtime.execute()` valida a chamada, cria o `JobSpec` e inclui o trace efetivo, request ID e
-provenance original. O adapter persiste o envelope; o handle também expõe esse trace. No
-worker, `runtime.executeJob()` revalida o envelope e executa um span filho, preservando a
-cadeia request → enqueue → job sem aceitar baggage ou campos extras no carrier.
+`runtime.execute()` valida a chamada, cria o `JobSpec` e inclui o trace efetivo, o request ID e a
+provenance original. O adapter persiste esse envelope, e o handle também expõe o trace. No worker,
+`runtime.executeJob()` revalida o envelope e executa um span filho, preservando a cadeia requisição
+→ enfileiramento → job sem aceitar baggage ou campos extras.
 
 ## Driver
 
@@ -43,26 +46,41 @@ import { bullmqQueue } from '@softize/opus/queue/bullmq'
 const queue = bullmqQueue({ queue: new Queue('opus', { connection: { host: 'localhost' } }) })
 ```
 
-Redis-backed (durável, entre-processos, retries). Peers opcionais (`bullmq`, `ioredis`) só
-para quem usa o driver.
+O driver usa Redis por meio do BullMQ, com durabilidade, entrega entre processos e novas tentativas.
+`bullmq` é dependência opcional: só precisa ser instalado por quem usa o driver.
 
-## No runtime
+## Declarar a action em background
+
+Configure a fila no runtime e declare `background` no binding da action:
 
 ```ts
 const runtime = createRuntime({
   // …server/data…
   queue,
 })
+
+export const relatorioGerar = bindAction(relatorioGerarContract, {
+  background: { enabled: true, retry: { attempts: 3 }, progress: true },
+  handler: async (ctx, input, loaded, progress) => {
+    await progress?.report({ percent: 50, message: 'Consultando dados' })
+    return gerarRelatorio(input)
+  },
+})
 ```
 
-A action declara `background: { enabled: true }` (+ retry/priority no contrato); chamá-la devolve um
-`JobHandle` em vez do resultado, e o cliente pola `status(jobId)` (ou `subscribe`) até
-`done`/`failed`.
+Só actions `simple` e `form` executam em background; além de `retry` e `progress`, a configuração
+aceita `queue`, `priority` e `timeout`. Em uma action `list` ou `view`, o tipo do binding aceita
+`background`, mas o runtime o ignora e executa a action na própria requisição. Para evitar essa
+surpresa, o runtime avisa ao registrar a action fora de produção (`runtime.action_field_ignored`), e
+o [`opus check`](/docs/cli) aponta a regra `ignored-by-kind`. Sem `QueueAdapter`, a chamada falha com
+`runtime.queue_required`. Chamar a action devolve um `JobHandle` em vez do resultado. O Opus não
+monta uma rota de acompanhamento: exponha `queue.status(jobId)` ou `queue.subscribe` por uma action
+ou rota do próprio app até o job chegar a `done` ou `failed`.
 
 ## Worker BullMQ
 
-O app continua dono do `Worker` e da reidratação de autenticação. O processor chama
-`executeJob()` — nunca `execute()`, que criaria outro job:
+O app continua dono do `Worker` e de reconstruir a autenticação de quem enfileirou. O processor
+chama `executeJob()`, e não `execute()`, que criaria outro job:
 
 ```ts
 new Worker('opus', async (job) => {
@@ -76,13 +94,13 @@ new Worker('opus', async (job) => {
 }, { connection })
 ```
 
-O runtime confirma que o actor reidratado corresponde a `spec.ctx.userId`; tenant, request,
-trace e provenance vêm do envelope. O driver mapeia `attempts`, backoff nativo e prioridade.
-Multiplicador exponencial diferente de 2 ou `maxMs` exige `backoffStrategy` custom do worker e
-é rejeitado pelo driver em vez de ser silenciosamente ignorado. `timeout` permanece no
-envelope para o worker aplicar, pois não é uma opção de execução do `Queue.add`.
+O runtime confirma que o usuário reconstruído corresponde a `spec.ctx.userId`; tenant, request,
+trace e provenance vêm do envelope. O driver traduz `attempts`, o backoff nativo e a prioridade para
+o BullMQ. Um backoff exponencial com multiplicador diferente de 2 ou com `maxMs` exige uma
+`backoffStrategy` própria no worker, e o driver o recusa em vez de ignorá-lo em silêncio. `timeout`
+permanece no envelope para o worker aplicar, porque não é uma opção de execução do `Queue.add`.
 
 ## Limites atuais
 
-Driver hoje: `bullmq` (Redis). In-memory para dev e outros backends (SQS, pg-boss…) entram
-por reincidência.
+O único driver é o `bullmq`. Uma fila em memória para desenvolvimento e outros backends, como SQS e
+pg-boss, ainda não existem.

package/src/ui/docs/content/radio-group.md

@@ -1,8 +1,10 @@
 ## Escolha única
 
-Use `RadioGroup` quando todas as opções mutuamente exclusivas precisarem permanecer visíveis. Cada
-`RadioGroupItem` declara um `value` e deve estar associado a um `Label`. `defaultValue` define a
-opção inicial no modo não controlado.
+Use `RadioGroup` quando todas as opções mutuamente exclusivas precisarem permanecer visíveis. Com
+muitas opções, prefira [`Select`](/ui/select); para ligar ou desligar um único item, use
+[`Checkbox`](/ui/checkbox) ou [`Switch`](/ui/switch). Cada `RadioGroupItem` declara um `value` e
+deve estar associado a um `Label`, escrito logo depois do item. `defaultValue` define a opção
+inicial no modo não controlado.
 
 ```tsx preview col-start
 <RadioGroup defaultValue="balanced">
@@ -68,6 +70,25 @@ bloquear todas as opções, aplique `disabled` ao `RadioGroup`.
 </RadioGroup>
 ```
 
+## Estado inválido
+
+Quando a escolha for obrigatória e nenhuma opção estiver marcada, declare `aria-invalid` em cada
+`RadioGroupItem` e explique o que falta em um texto associado ao grupo por `aria-describedby`.
+
+```tsx preview col-start
+<RadioGroup aria-describedby="review-mode-error">
+  <div className="flex items-center gap-2">
+    <RadioGroupItem id="review-auto" value="auto" aria-invalid />
+    <Label htmlFor="review-auto">Revisar automaticamente</Label>
+  </div>
+  <div className="flex items-center gap-2">
+    <RadioGroupItem id="review-manual" value="manual" aria-invalid />
+    <Label htmlFor="review-manual">Revisar manualmente</Label>
+  </div>
+</RadioGroup>
+<FieldError id="review-mode-error">Escolha como a sessão será revisada.</FieldError>
+```
+
 ## Propriedades de RadioGroup
 
 | Propriedade | Tipo | Padrão | Descrição |
@@ -82,4 +103,5 @@ bloquear todas as opções, aplique `disabled` ao `RadioGroup`.
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `value` | `string` | | Valor que o item atribui ao grupo quando selecionado. |
-| `disabled` | `boolean` | `false` | Desabilita somente este item; o `Label` associado acompanha o estado. |
+| `disabled` | `boolean` | `false` | Desabilita somente este item; o `Label` escrito logo depois dele acompanha o estado. |
+| `aria-invalid` | `boolean` | | Aplica a borda e o anel de erro ao item. |

package/src/ui/docs/content/router.md

@@ -19,11 +19,13 @@ function App() {
 O router oferece leitura reativa da URL e `navigate`; o aplicativo decide o que renderizar. Ele não
 inclui tabela de rotas, parâmetros tipados nem carregamento de dados.
 
-A régua: se a sua tela precisa de casamento de padrão (`/users/:id/posts/:postId`), params tipados ou data loaders, o caso pede uma biblioteca de rotas, não isto. Um app de back-office com uma dúzia de destinos quase nunca precisa.
+Se a tela precisa casar padrões como `/users/:id/posts/:postId`, receber parâmetros tipados ou
+carregar dados por rota, use uma biblioteca de rotas. Um app de back-office com uma dúzia de
+destinos costuma dispensar esses recursos.
 
 ## As quatro peças
 
-| | |
+| API | Comportamento |
 |---|---|
 | `usePathname()` | O pathname como estado reativo. |
 | `useSegments()` | Os segmentos, já sem os vazios: `/settings/users` → `['settings','users']`. |
@@ -32,15 +34,23 @@ A régua: se a sua tela precisa de casamento de padrão (`/users/:id/posts/:post
 
 ## Comportamentos preservados
 
-**Destino igual é no-op.** `navigate` resolve o destino com `new URL` e compara o `href` inteiro — não faz nada se você já está exatamente lá. Sem isso, clicar duas vezes no mesmo item do menu empilha entradas idênticas e o botão "voltar" não sai do lugar.
+**Navegar para o destino atual não cria entrada.** `navigate` resolve o destino com `new URL` e
+compara o `href` inteiro; se a pessoa já está exatamente lá, nada acontece. Assim, clicar duas vezes
+no mesmo item do menu não empilha entradas idênticas, e o botão Voltar continua saindo da página.
 
-Comparar strings cruas parece bastar e não basta, em duas frentes. O **hash**: estando em `/a#secao`, `navigate('/a')` pareceria destino repetido e a âncora nunca sairia da URL. E o **encoding**: `window.location` devolve `/relatórios` como `/relat%C3%B3rios`, então a comparação crua nunca casa e cada clique empilha — bem no caso pt-BR, e no ``navigate(`/reports?report=${arquivo}`)`` com nome de arquivo acentuado.
+A comparação usa a URL resolvida, e não o texto cru, por dois motivos. O hash: estando em
+`/a#secao`, `navigate('/a')` precisa remover a âncora, e não ser tratado como destino repetido. E a
+codificação: `window.location` devolve `/relatórios` como `/relat%C3%B3rios`, então uma comparação
+crua nunca casaria e cada clique empilharia uma entrada, o que afeta caminhos acentuados e
+chamadas como ``navigate(`/reports?report=${arquivo}`)`` com nome de arquivo acentuado.
 
 **A notificação usa um evento do navegador.** Como `pushState` não dispara `popstate`, `navigate`
 emite o evento explicitamente. Isso mantém listeners existentes e cópias diferentes do pacote
 sincronizados pela mesma janela.
 
-**`useSyncExternalStore`, não `useState`.** Ler `window.location` dentro de `useState`/`useEffect` sofre *tearing* no modo concurrent: dois componentes podem renderizar o mesmo commit com URLs diferentes. As cópias que este módulo substituiu faziam isso.
+**Todos os componentes leem a mesma URL.** Os hooks usam `useSyncExternalStore`. Ler
+`window.location` dentro de `useState` ou `useEffect` permite que, na renderização concorrente, dois
+componentes mostrem URLs diferentes no mesmo commit.
 
 ## `replace`: quando o passo não é história
 
@@ -48,14 +58,23 @@ sincronizados pela mesma janela.
 navigate(`/reports?report=${file}`, { replace: true })
 ```
 
-Use quando a mudança não merece uma volta do botão "voltar" — um rascunho que ganha id no meio do fluxo, um filtro que a pessoa ajusta várias vezes seguidas. O default (`pushState`) é o certo para navegação de verdade.
+Use `replace` quando a mudança não deve virar um passo do botão Voltar: um rascunho que ganha id no
+meio do fluxo, um filtro que a pessoa ajusta várias vezes seguidas. Para uma navegação entre
+destinos, mantenha o padrão, `pushState`.
 
 ## SSR
 
-Os hooks têm snapshot de servidor constante (`/` e busca vazia): renderizam sem `window` e reconciliam com a URL real no primeiro render do cliente. Se a sua página precisa do path correto **no HTML servido**, isto não resolve — aí o path tem que vir do framework, por prop.
+No servidor, os hooks usam um valor fixo (`/` e busca vazia): renderizam sem `window` e passam a
+refletir a URL real no primeiro render do cliente. Se a página precisa do caminho correto no HTML
+servido, receba o caminho do framework por prop.
 
-O `navigate` **não** tem essa cortesia: ele toca `window` direto e estoura no servidor. É de propósito — ler a URL sem browser tem resposta razoável, navegar não tem, e engolir a chamada em silêncio esconderia o erro de uso.
+`navigate` acessa `window` diretamente e lança um erro quando chamado no servidor. Ler a URL fora
+do navegador tem uma resposta razoável; navegar não tem, e ignorar a chamada em silêncio esconderia
+o erro de uso.
 
-## Destino externo não é problema daqui
+## Validar destinos vindos de fora
 
-`navigate` espera um caminho da própria origem. Validar destino que veio de terceiro — o `?redirect=` de um pós-login, por exemplo — é responsabilidade de quem recebe esse input, e a checagem certa é resolver com `new URL(valor, origin)` e comparar `origin`, não olhar prefixo.
+`navigate` espera um caminho da própria origem e não valida destinos. Quando o destino vem de fora,
+como o `?redirect=` de um pós-login, valide-o antes de navegar: resolva com
+`new URL(valor, origin)` e compare o `origin` do resultado, em vez de conferir apenas o prefixo do
+texto.

package/src/ui/docs/content/runtime.md

@@ -4,94 +4,130 @@ title: Runtime & adapters
 
 # Runtime & adapters
 
-O Opus não é framework — é **protocolo + SDK**: você compõe o runtime a partir de
-adapters plugáveis, e cada capacidade é opcional. O litmus é a inversão de controle:
-o runtime não toma o seu app; o seu app monta o runtime com as peças que quer.
+O runtime executa as actions registradas e entrega a elas as capacidades que o app configurou:
+servidor HTTP, banco, autenticação, auditoria e as demais. Cada capacidade é um adapter opcional.
+O app monta o runtime com as peças de que precisa, e o Opus não assume o controle do restante da
+aplicação.
 
 ## O modelo
 
-> Todo adapter implementa `name`/`kind`; `init`/`dispose`/`healthCheck` são opcionais e
-> entram no ciclo de vida do runtime (start inicializa, dispose desliga em ordem reversa,
-> healthCheck agrega).
+Todo adapter declara `name` e `kind`. `init`, `dispose` e `healthCheck` são opcionais e acompanham o
+ciclo de vida do runtime: `start()` inicializa os adapters, `dispose()` os desliga em ordem inversa
+e `healthCheck()` reúne o estado de todos.
 
 ```ts
 import { createRuntime } from '@softize/opus/core'
 
 const runtime = createRuntime({
-  server: fastifyServer({ app }),      // monta as actions como endpoints
+  server: fastifyServer({ app }),      // expõe as actions como endpoints
   data: kyselyData({ db }),            // fornece ctx.db
-  auth: makeAuthAdapter(),             // resolve user/tenant/can
-  audit: [pgAudit({ pool })],          // trilha de auditoria (N sinks)
-  observability: makeObservability(),  // span ativo + TraceContext vendor-neutral
+  auth: jwtAuth({ secret, mapUser }),  // resolve user, tenant e can
+  audit: [pgAudit({ pool })],          // trilha de auditoria; aceita vários sinks
+  observability: openTelemetryObservability(), // span ativo e trace sem fornecedor fixo
   storage: fsStorage({ root }),        // fornece ctx.storage (experimental)
   config: { env, i18n: { defaultLocale: 'pt-BR' } },
 })
 
-runtime.register([dealsDomain, billingDomain]) // não registrado = não existe
+runtime.register([workspaceDomain])
 await runtime.start()
 ```
 
+## Registrar domínios
+
+Só o que foi registrado existe para o runtime: uma action fora do registro não é montada no servidor
+nem pode ser executada. `runtime.register` aceita domínios criados com `defineDomain` e também
+actions, reactions e schedules soltos, em uma mesma lista. Um domínio é achatado com seus
+subdomínios; um nome repetido de action, reaction, schedule ou Produto de Dados lança erro, inclusive
+entre domínios registrados separadamente.
+
+O `start()` falha quando há reactions registradas sem `eventBus` (`runtime.eventbus_required`) ou
+schedules sem `scheduler` (`runtime.scheduler_required`). A declaração de um domínio está em
+[Actions & contratos](/docs/actions).
+
 ## As capacidades
 
-> Um subpath por driver; quem não usa, não instala (peers opcionais onde há dependência
-> pesada). A tabela é o mapa — cada linha é um recurso do protocolo.
+Cada driver fica num subpath próprio do pacote. Drivers que dependem de bibliotecas maiores as
+declaram como dependências opcionais: só quem usa o driver as instala.
 
 | Capacidade | Fornece | Driver pronto |
 |---|---|---|
-| `server` | monta as actions (HTTP) | `fastifyServer` — `@softize/opus/server/fastify` · `nodeServer` — `…/server/node` |
-| `data` | `ctx.db` + drift-check + CRUD | `kyselyData`, `kyselyRepo`, `crudActions` — `@softize/opus/data/kysely` |
-| `auth` | `user`/`tenantId`/`can` do contexto | `jwtAuth` — `…/auth/jwt` · `betterAuthSession` — `…/auth/better-auth` |
+| `server` | expõe as actions por HTTP | `fastifyServer` — `@softize/opus/server/fastify` · `nodeServer` — `…/server/node` |
+| `data` | `ctx.db`, verificação de drift e CRUD | `kyselyData`, `kyselyRepo`, `crudActions` — `@softize/opus/data/kysely` |
+| `auth` | `user`, `tenantId` e `can` do contexto | `jwtAuth` — `…/auth/jwt` · `betterAuthSession` — `…/auth/better-auth` |
 | `audit` | trilha por execução de action | `pgAudit` — `…/audit/pg` · `consoleAudit` — `…/audit/console` |
 | `logger` | `ctx.log` estruturado | `pinoLogger` — `@softize/opus/log/pino` |
-| `observability` | span ativo + propagação de trace | `openTelemetryObservability` — `@softize/opus/observability/opentelemetry` |
-| `eventBus` | `ctx.emit` + **reactions** | `mittEvents` — `@softize/opus/events/mitt` |
+| `observability` | span ativo e propagação de trace | `openTelemetryObservability` — `@softize/opus/observability/opentelemetry` |
+| `eventBus` | `ctx.emit` e reactions | `mittEvents` — `@softize/opus/events/mitt` |
 | `queue` | jobs em background | `bullmqQueue` — `@softize/opus/queue/bullmq` |
-| `scheduler` | **schedules** (cron/intervalo) | `nodeCronScheduler` — `@softize/opus/scheduler/node-cron` |
-| `storage` | `ctx.storage` (arquivos) | `fsStorage` — `…/storage/fs` · `s3Storage` — `…/storage/s3` |
-| `cache` | `ctx.cache` (leitura, experimental) | `memoryCache` — `@softize/opus/cache/memory` |
-| `ai` | `ctx.ai` (complete/extract) | `anthropicAi` — `@softize/opus/ai/anthropic` |
-| `client` | chamar actions de fora (stubs) | `fetchClient` — `@softize/opus/client/fetch` |
+| `scheduler` | schedules por cron ou intervalo | `nodeCronScheduler` — `@softize/opus/scheduler/node-cron` |
+| `storage` | `ctx.storage` para arquivos | `fsStorage` — `…/storage/fs` · `s3Storage` — `…/storage/s3` |
+| `cache` | `ctx.cache` de leitura (experimental) | `memoryCache` — `@softize/opus/cache/memory` |
+| `ai` | `ctx.ai`: `complete`, `extract`, `run` e `runStream` | `anthropicAi` — `@softize/opus/ai/anthropic` |
+| `client` | chamar actions de fora do servidor | `fetchClient` — `@softize/opus/client/fetch` |
 
-Fora do runtime, mas parte do protocolo: o harness de teste (`runAction`/`testContext`
-— `@softize/opus/testing`) roda uma action em unidade com o mesmo pipeline do
-`execute`. Ver **Testes de action**.
+`fastifyServer` devolve o adapter diretamente. `nodeServer` devolve `{ adapter, handler, hasRoute }`:
+passe `adapter` ao runtime e ligue `handler` a um servidor `node:http`, ao Vite ou a um middleware no
+estilo connect.
+
+```ts
+import { createServer } from 'node:http'
+import { nodeServer } from '@softize/opus/server/node'
+
+const node = nodeServer()
+const runtime = createRuntime({ server: node.adapter })
+createServer(node.handler).listen(3000)
+```
+
+Fora do runtime, o harness de teste (`runAction` e `testContext`, de `@softize/opus/testing`) executa
+uma action em unidade com as etapas centrais do `execute`: valida a entrada, exige autenticação
+quando a action não é pública, avalia o `authorize`, roda o handler e valida a saída. Ele não roda os
+`loads` (os dados carregados entram pela opção `loaded`) nem grava audit. Veja
+[Testes de action](/docs/testing).
 
 ## O contexto do handler
 
-> O `ctx` é a soma do que os adapters fornecem — sem adapter, o campo é `null`/`unknown`
-> e o handler decide como degradar.
+O `ctx` recebido pelo handler reúne o que os adapters fornecem. Sem o adapter correspondente, o
+campo chega como `null`, ou como `undefined` no caso de `db`, e o handler decide como seguir.
+
+- `user`, `tenantId` e `can`, do adapter `auth`.
+- `db`, do adapter `data`.
+- `log`, do `logger`; sem ele, o runtime usa um logger de console.
+- `emit`, que publica no `eventBus`.
+- `storage`, `cache` e `ai`, dos adapters homônimos.
+- `provenance`, que identifica a origem da execução: HTTP, schedule, reaction, job, agente de IA ou
+  integração.
+- `trace`, quando há contexto de trace.
+- `meta`, com dados livres da chamada.
 
-`user`/`tenantId`/`can` (auth) · `db` (data) · `log` (logger) · `emit` (eventBus) ·
-`storage` (storage) · `cache` (cache) · `ai` (ai) · `provenance` (quem disparou: http, schedule,
-reaction…) · `trace` (quando configurado) · `meta`.
+## Trace e observabilidade
 
-O core não depende de OpenTelemetry. O `ObservabilityAdapter` envolve actions e reactions
-com `runInSpan`; o `TraceContext` efetivo também segue para resultado, audit e eventos. Os
-envelopes de job recebem o trace da execução que enfileirou; `executeJob()` cria a execução
-filha no worker sem reenfileirar a action.
-Falha de instrumentação é lenient e nunca repete o handler.
+O core não depende de OpenTelemetry. O `ObservabilityAdapter` envolve actions e reactions com
+`runInSpan`, e o `TraceContext` efetivo segue para o resultado, o audit e os eventos. Um job recebe
+o trace da execução que o enfileirou, e `executeJob()` cria a execução filha no worker sem
+enfileirar a action de novo. Uma falha de instrumentação é tratada de forma tolerante e nunca
+executa o handler outra vez.
 
-O core não extrai headers HTTP. Os drivers Fastify e Node podem fornecer
-`ContextBase.trace` com `traceContext: 'w3c'`; o opt-in é desativado por default. Outros
-transportes continuam responsáveis por sua fronteira. Em audit, o contexto novo usa
-`traceContext`; o campo `trace` legado continua disponível sem mudança.
+O core não lê headers HTTP. Os drivers Fastify e Node preenchem `ContextBase.trace` com a opção
+`traceContext: 'w3c'`, desativada por padrão; outros transportes continuam responsáveis pela própria
+fronteira. O registro de audit traz dois campos: `traceContext`, com o contexto de trace (`traceId`, `spanId` e flags), e `trace`, com o
+`requestId` e a action de origem (`parentActionId`). Os detalhes estão em [Observabilidade](/docs/observability).
 
-Para actions, o callback observável resolve com `ActionResult`: `resultKind: 'action-result'`
-indica que o driver deve inspecionar `result.ok`. Uma Promise resolvida com `ok:false` ainda
-representa span de erro. Reactions usam `resultKind: 'void'` e rejeitam em falha.
+Para actions, a execução observada resolve com `ActionResult` e declara `resultKind:
+'action-result'`: o driver inspeciona `result.ok`, e uma Promise resolvida com `ok: false` ainda
+representa um span de erro. Reactions usam `resultKind: 'void'` e rejeitam em caso de falha.
 
-## Reactions e schedules
+## Execução sem requisição
 
-> Os dois jeitos de código rodar SEM request: evento de domínio dispara reaction;
-> tempo dispara schedule (que executa uma action, com provenance própria).
+Duas formas de código rodam sem uma requisição: um evento de domínio dispara uma
+[reaction](/docs/events), e o tempo dispara um [schedule](/docs/scheduler), que executa uma action
+com provenance própria. Ambos são registrados junto com as actions, e o manifest projeta os três.
 
-Declarados como as actions e registrados no mesmo `runtime.register` — o manifest
-projeta os três. `opus introspect` lista reactions, schedules e o wiring entre eles, mas por
-enquanto só reconhece actions declaradas com `defineAction`: as do split `defineContract` +
-`bindAction` ficam de fora do modelo que ele monta.
+`opus introspect` lista reactions, schedules e as ligações entre eles, mas só reconhece
+declarações feitas com `defineAction`, `defineReaction` e `defineSchedule`. Actions do par
+`defineContract` e `bindAction` e reactions do par `defineReactionContract` e `bindReaction` ficam de
+fora do modelo que ele monta.
 
-## Referência profunda
+## Referência completa
 
-O contrato completo (tipos, garantias, ordem de execução, erros) vive no
-`docs/protocol.md` **dentro do pacote** — como o changelog, viaja com a versão
-que você instalou.
+O contrato completo, com tipos, garantias, ordem de execução e erros, está em `docs/protocol.md`,
+dentro do pacote instalado. Como o changelog, ele acompanha a versão que o projeto usa.

package/src/ui/docs/content/scheduler.md

@@ -4,62 +4,94 @@ title: Agendador
 
 # Agendador
 
-Use um schedule para executar uma action por cron ou intervalo. O `SchedulerAdapter` registra o
-agendamento e o runtime executa a action com provenance `schedule`, preservando sua rastreabilidade.
+Use um schedule para executar uma action por cron ou em intervalos, sem uma requisição. O
+`SchedulerAdapter` registra o agendamento, e o runtime executa a action com provenance `schedule`,
+que aparece no audit e no contexto do handler.
 
 ## O contrato
 
 ```ts
-interface SchedulerAdapter {
+interface SchedulerAdapter extends Adapter {
+  name: string                // herdado de Adapter; identifica o driver
+  kind: 'scheduler'
   register(spec: ScheduleDef, fire: () => Promise<void> | void): Unsubscribe
 }
 
 interface ScheduleDef {
   name: string
-  action: string              // action do registry, executada quando dispara
-  cron?: string               // '0 9 * * *' (9h todo dia)
-  every?: string              // '1h', '30m', '15s' — atalho de intervalo
-  timezone?: string           // IANA, ex.: 'America/Sao_Paulo' (sem ele: hora local do processo)
-  input?: unknown | (() => unknown | Promise<unknown>)   // estático ou dinâmico
-  enabled?: boolean
+  action: string              // action registrada, executada a cada disparo
+  cron?: string               // '0 9 * * *' (todo dia às 9h)
+  every?: string              // '15s', '5m', '1h', '1d': atalho de intervalo
+  timezone?: string           // IANA, como 'America/Sao_Paulo'; sem ela, vale a hora local do processo
+  input?: unknown | (() => unknown | Promise<unknown>)   // fixo ou calculado a cada disparo
+  enabled?: boolean           // padrão true
+  description?: string
+  tags?: string[]
 }
 ```
 
-O timing é exclusivo: `cron` **ou** `every`. A action referenciada tem que existir no
-registry.
+Declare `cron` ou `every`, não os dois. `every` aceita segundos e minutos até 59, horas até 23 e
+somente `1d` para dias; intervalos maiores usam `cron`. Sem `input`, a action recebe `{}`.
 
 ## Driver
 
 ```ts
 import { nodeCronScheduler } from '@softize/opus/scheduler/node-cron'
 
-const scheduler = nodeCronScheduler()   // in-process
+const scheduler = nodeCronScheduler() // no mesmo processo do runtime
 ```
 
-## No runtime
+## Declarar no domínio
+
+Declare o schedule com `defineSchedule` e registre-o no domínio, ao lado da action que ele executa:
 
 ```ts
-import { defineSchedule } from '@softize/opus/core'
+import { createRuntime, defineDomain, defineSchedule } from '@softize/opus/core'
+import { caixaFechar } from './caixa-fechar.ts' // a action 'caixa.fechar', definida com bindAction
 
-// Declarado no domínio, junto das actions:
 const fecharDia = defineSchedule({
-  name: 'fechar-dia',
+  name: 'caixa.fechar-dia',
   action: 'caixa.fechar',
   cron: '0 23 * * *',
   timezone: 'America/Sao_Paulo',
 })
 
+export const caixaDomain = defineDomain({
+  name: 'caixa',
+  actions: { caixaFechar },
+  schedules: [fecharDia],
+})
+
 const runtime = createRuntime({
   // …server/data…
   scheduler,
 })
+runtime.register([caixaDomain])
+await runtime.start()
 ```
 
-O runtime registra os schedules do domínio no `start()` e chama a action quando o tempo bate
-— nada de disparar no handler.
+No `start()`, o runtime confere se cada schedule aponta para uma action registrada no mesmo runtime
+e depois o registra no adapter. Um nome sem action registrada interrompe o `start()` com
+`runtime.schedule_action_not_found`, antes de inicializar os adapters; a mensagem lista cada
+schedule e a action que ele procurou. Com schedules registrados e sem `scheduler`, o `start()`
+falha com `runtime.scheduler_required`. Um schedule com `enabled: false` não é registrado nem
+conferido, então pode apontar para uma action que ainda não existe no ambiente.
+
+## Preparar a action agendada
+
+O schedule executa a action sem usuário: `ctx.user` é `null` e `ctx.can` nega tudo. Por isso, a
+action alvo precisa declarar `public: true`; sem isso, cada disparo termina em
+`auth.unauthenticated`. Para que ela não fique acessível por HTTP, declare também `internal: true`:
+os servidores do Opus não expõem actions internas, e o schedule continua executando-a pelo runtime.
+
+Quando um disparo não conclui a action, o runtime registra um erro no log com o schedule, a action,
+o código e a mensagem do erro; o agendamento continua ativo e o próximo disparo executa a action de
+novo. Uma falha dentro do pipeline da action, como `auth.unauthenticated` ou um erro do handler,
+também fica registrada no audit. O callback `onError` do driver recebe somente erros lançados antes
+da execução, como uma falha na função `input`.
 
 ## Limites atuais
 
-Driver hoje: `node-cron` (in-process — some se o processo cair; em um cluster, cada nó
-dispararia). Backends duráveis/distribuídos (BullMQ repeatable, Temporal…) entram por
-reincidência.
+O único driver é o `node-cron`, que roda no mesmo processo: o agendamento some se o processo cair e,
+em um cluster, cada nó dispara o mesmo schedule. O modo design do Vite não registra schedules.
+Backends duráveis ou distribuídos, como jobs repetidos do BullMQ ou Temporal, ainda não têm driver.