@softize/opus 20.1.0 → 21.0.0

package/src/core/schedules.ts

@@ -11,8 +11,9 @@
  *   - Schedule = tempo dispara
  *
  * Runtime registra no SchedulerAdapter no `start()`. Quando o tempo
- * configurado bate, o scheduler chama `runtime.execute(action, input, ctx)`
- * com `ctx.provenance = { kind: 'schedule', scheduleName }`.
+ * configurado bate, o runtime executa a action como o sistema, com
+ * `ctx.provenance = { kind: 'schedule', scheduleName }`; a action precisa
+ * declarar `automatable: true` (ou `public: true`). Ver ADR 0028.
  *
  * Ver §16 do protocolo.
  */

package/src/core/types.ts

@@ -255,10 +255,11 @@ export interface User {
 export type CanFn = (permission: string, resource?: unknown) => boolean | Promise<boolean>
 
 /**
- * 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`.
+ * Função que emite um `DomainEvent` pelo `EventBusAdapter`. Em `ActionContext.emit`, publica
+ * qualquer evento; um evento fora do `emits` da action gera aviso com
+ * `config.warnUndeclaredEmits`. Em `ReactionContext.emit`, publica somente eventos listados no
+ * `emits` da reaction e descarta os demais (aviso `runtime.reaction_emit_ignored`); a cadeia de
+ * reactions para em `config.maxReactionDepth`. Ver ADR 0027.
  */
 export type EmitFn = <T = unknown>(
   event: string,
@@ -295,7 +296,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`. */
+  /** Publica os eventos declarados em `emits` da reaction; descarta os demais. Ver `EmitFn`. */
   emit: EmitFn
   storage: StorageAdapter | null
   cache: CacheAdapter | null
@@ -303,6 +304,12 @@ export interface ReactionContext {
   provenance: Provenance
   trace?: TraceContext
   meta: Record<string, unknown>
+  /**
+   * Abortado quando a tentativa excede o `timeout` da reaction. O runtime sempre preenche o
+   * campo; ele é opcional para quem monta o contexto à mão em testes. Um handler que ignora o
+   * sinal continua executando depois do timeout. Ver ADR 0026.
+   */
+  signal?: AbortSignal
 }
 
 // =============================================================================
@@ -387,11 +394,26 @@ export interface DomainEvent<T = unknown> {
   actor: { id: string | null; type?: 'user' | 'system' | 'integration' }
   tenant?: string | null
   data: T
+  /**
+   * A action que iniciou a cadeia. Um evento publicado por reaction herda o `source` do evento
+   * que ela processava, e `provenance.sourceActionId` continua batendo com o audit da action.
+   */
   source: {
     action: string
     actionId: string
     correlation?: string
   }
+  /**
+   * Presente só em evento publicado por reaction: qual reaction o publicou, a partir de qual
+   * evento e a que profundidade da cadeia (1 = primeira reaction depois da action). Evento
+   * emitido por action não tem `cause` e está na profundidade 0. Ver ADR 0027.
+   */
+  cause?: {
+    reaction: string
+    eventId: string
+    eventType: string
+    depth: number
+  }
   trace?: TraceContext
   meta?: Record<string, unknown>
 }
@@ -434,6 +456,12 @@ export interface JobSpec {
     requestId?: string
     trace?: TraceContext
     originalProvenance?: Provenance
+    /**
+     * Presente quando o próprio runtime enfileirou o job numa execução do sistema (o disparo de um
+     * schedule). O worker só reconstrói a identidade de sistema com esta marca; a provenance não
+     * basta, porque vem do chamador. Ver ADR 0028.
+     */
+    system?: true
   }
   config: {
     queue?: string
@@ -828,6 +856,11 @@ export interface ActionBase<In, Out, ParsedIn = In> {
 
   // — Integração —
   ai?: boolean | AIConfig
+  /**
+   * Aceita execução pelo sistema, sem usuário, quando um schedule a dispara. Sem este opt-in,
+   * a execução pelo sistema de uma action não pública termina em `auth.system_forbidden`. Não
+   * abre a action a chamadores anônimos. Ver `isSystemActor` e ADR 0028.
+   */
   automatable?: boolean
   internal?: boolean
   successStatus?: number
@@ -950,9 +983,17 @@ export interface ReactionDef<Event = unknown> {
 
   handler: ReactionHandlerFn<Event>
 
+  /** Eventos que o handler pode publicar com `ctx.emit`; os demais são descartados (ADR 0027). */
+  emits?: string[]
+
+  // — Política de entrega (ADR 0026) —
+  /** Total de execuções do handler, com espera opcional entre elas. Sem `retry`, roda uma vez. */
   retry?: { attempts: number; backoff?: BackoffSpec }
+  /** Prazo de cada tentativa, em ms; ao vencer, aborta `ctx.signal`. */
   timeout?: number
+  /** Chave de idempotência: evento com chave já vista em `config.dedupCacheTtl` é descartado. */
   dedup?: (event: DomainEvent<Event>) => string
+  /** Máximo de tentativas simultâneas desta reaction. Padrão 1. */
   concurrency?: number
 
   authorize?: (
@@ -1419,8 +1460,8 @@ export interface SchedulerAdapter extends Adapter {
    * Registra um schedule e retorna função pra cancelar. Chamado pelo
    * runtime no `start()` pra cada schedule.
    *
-   * Quando o tempo bater, o adapter chama `fire()` que internamente
-   * invoca runtime.execute() com provenance schedule.
+   * Quando o tempo bater, o adapter chama `fire()`, e o runtime executa a
+   * action como o sistema, com provenance schedule (ADR 0028).
    */
   register(spec: ScheduleDef, fire: () => Promise<void> | void): Unsubscribe
 }
@@ -1453,6 +1494,8 @@ export interface RuntimeConfig {
 
   // — Resiliência —
   dedupCacheTtl?: number
+  /** Chaves concluídas que o dedup guarda por reaction; acima disso, descarta a mais antiga. Padrão 10.000. */
+  dedupCacheMaxEntries?: number
   defaultRetry?: { attempts: number; backoff?: BackoffSpec }
 
   // — i18n —
@@ -1464,4 +1507,6 @@ export interface RuntimeConfig {
   // — Limites —
   maxConcurrentActions?: number
   maxConcurrentReactions?: number
+  /** Saltos de reaction que uma cadeia de eventos pode dar. Padrão 5 (ADR 0027). */
+  maxReactionDepth?: number
 }

package/src/testing/index.ts

@@ -9,10 +9,11 @@
  *     capturado em `emitted`, log capturado em `logged`, `can` configurável,
  *     storage plugável (ex.: `memStorage()`).
  *   • `runAction(action, input)` — o MESMO pipeline do `runtime.execute`, em unidade:
- *     valida input → gate `public` → `authorize` (string DSL ou closure, semântica
- *     idêntica, `loaded` incluso) → handler → valida output (pulado em `list`, como
- *     no runtime). Falha estoura o MESMO `ActionError` tipado do runtime
- *     (`validation.invalid_input`, `auth.unauthenticated`, `auth.forbidden`…).
+ *     valida input → gate de autenticação (`public`, usuário ou sistema `automatable`) →
+ *     `authorize` (string DSL ou closure, semântica idêntica, `loaded` incluso) → handler →
+ *     valida output (pulado em `list`, como no runtime). Falha estoura o MESMO
+ *     `ActionError` tipado do runtime (`validation.invalid_input`, `auth.unauthenticated`,
+ *     `auth.system_forbidden`, `auth.forbidden`…). A opção `schedule` executa como o sistema.
  *     Em `OPUS_MODE=design` roteia pro `mockHandler` como o runtime — contrato puro
  *     (sem handler) é testável em design; fora dele, erro claro (`testing.no_handler`).
  *   • `memStorage()` — StorageAdapter em memória pra testar handler que anexa
@@ -31,7 +32,7 @@ import { normalizeKey } from '../storage/index.ts'
 import { error } from '../core/errors.ts'
 // Import direto do runtime (fora do index público): a régua handler×mockHandler
 // tem UMA fonte — o harness nunca pode divergir do execute().
-import { isOpusDesignMode } from '../core/runtime.ts'
+import { assertAuthenticated, isOpusDesignMode, markSystemActor } from '../core/runtime.ts'
 import type {
   ActionContext,
   ActionKind,
@@ -201,6 +202,7 @@ export interface TestableAction<In, Out, ParsedIn = In> {
   name: string
   kind?: ActionKind
   public?: boolean
+  automatable?: boolean
   authorize?: AuthorizeSpec<ParsedIn>
   input: Schema<In, ParsedIn>
   output: Schema<Out> | Schema<unknown, Out>
@@ -215,6 +217,7 @@ export interface TestableListAction<In, Item, ParsedIn = In> {
   name: string
   kind: 'list'
   public?: boolean
+  automatable?: boolean
   authorize?: AuthorizeSpec<ParsedIn>
   input: Schema<In, ParsedIn>
   output: Schema<Item> | Schema<unknown, Item>
@@ -233,6 +236,12 @@ export interface TestableListAction<In, Item, ParsedIn = In> {
 export interface RunActionOptions extends TestContextOptions {
   /** Substitui os loaders (não rodam em unidade): vai pro handler e pro evalCtx do authorize. */
   loaded?: Record<string, unknown>
+  /**
+   * Executa como o sistema, no disparo do schedule com este nome: `user` é `null`, `can` nega
+   * tudo, a provenance é `schedule` e `isSystemActor(ctx)` responde `true`. Como no runtime, a
+   * action precisa ser `automatable` (ou `public`); senão, `auth.system_forbidden`.
+   */
+  schedule?: string
 }
 
 export interface RunActionResult<Out> extends TestContext {
@@ -261,7 +270,7 @@ async function validate<T>(
 
 /**
  * Roda uma action em UNIDADE com o pipeline do `runtime.execute`: valida input →
- * gate `public` → authorize → handler → valida output. Sucesso devolve o output
+ * gate de autenticação → authorize → handler → valida output. Sucesso devolve o output
  * validado + o contexto observável (`emitted`, `logged`); falha estoura o mesmo
  * `ActionError` do runtime — afirme com `expect(...).rejects`.
  *
@@ -284,19 +293,21 @@ export async function runAction<In, Out, ParsedIn = In>(
   input: unknown,
   options: RunActionOptions = {},
 ): Promise<RunActionResult<Out>> {
-  const t = testContext(options)
+  const schedule = options.schedule
+  const t = testContext(
+    schedule === undefined ? options : { ...options, user: null, can: () => false },
+  )
   const { ctx } = t
+  if (schedule !== undefined) {
+    ctx.provenance = { kind: 'schedule', scheduleName: schedule }
+    markSystemActor(ctx)
+  }
   const loaded = options.loaded
 
   const parsed = await validate<ParsedIn>(action.input, input, 'input')
 
-  if (action.public !== true && ctx.user === null) {
-    throw error({
-      code: 'auth.unauthenticated',
-      category: 'authentication',
-      message: 'Autenticação necessária',
-    })
-  }
+  // O mesmo gate do runtime: pública, com usuário ou, pelo sistema, `automatable`.
+  assertAuthenticated(action, ctx)
 
   if (action.authorize !== undefined) {
     const spec = action.authorize

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

@@ -147,7 +147,8 @@ validações: `z.object({ tag: t.slug().zod(), contato: t.email().zod() })`. O `
 schema zod de cada tipo lógico (slug, email, phone, money…), importado de `@softize/opus/schema/zod`.
 
 A autorização é fechada por padrão: sem `public: true`, a action exige usuário autenticado; com
-`authorize`, exige também a permissão declarada.
+`authorize`, exige também a permissão declarada. `automatable: true` permite que um
+[schedule](/docs/scheduler) execute a action como o sistema, sem abri-la a chamadores anônimos.
 
 ## Prototipar com dados simulados
 

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

@@ -99,6 +99,16 @@ O que cada action captura se ajusta no contrato: `audit: false` desliga a audito
 `audit: { redact: ['senha'], output: false }` refina o registro. Por padrão, o registro inclui
 input, output e provenance.
 
+O `actor` diz quem executou. Uma pessoa aparece com `type: 'user'` e o próprio `id`; uma execução
+iniciada pelo sistema, como o disparo de um [schedule](/docs/scheduler), aparece com
+`{ id: null, type: 'system' }` e o nome do schedule na provenance.
+
+Reactions também geram registros, um por evento que chega ao handler. Eles têm `provenance.kind`
+igual a `reaction`, o nome da reaction em `action`, `meta: { kind: 'reaction', attempts }` e nenhum
+`actionKind`. O `input` traz só a identidade do evento (`id`, `type` e `source`), sem o payload, que
+já está no registro da action que emitiu. Um sink que filtra leituras por `actionKind` deve tratar
+esses registros à parte. Veja [Eventos](/docs/events).
+
 ## Limites atuais
 
 Os sinks só acrescentam registros: consulta e retenção ficam com o seu banco. Os drivers disponíveis

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

@@ -73,7 +73,11 @@ export const notaEmitir = bindAction(notaEmitirContract, {
 Antes do handler, o runtime verifica a chamada nesta ordem:
 
 1. Valida a entrada pelo schema do contrato.
-2. Sem `public: true`, exige `ctx.user`; sem usuário, responde `auth.unauthenticated`.
+2. Sem `public: true`, exige `ctx.user`; sem usuário, responde `auth.unauthenticated`. A exceção é
+   o disparo de um schedule, que executa como o sistema uma action com `automatable: true` e recebe
+   `auth.system_forbidden` nas demais (veja [Agendador](/docs/scheduler)). Para aceitar o sistema no
+   `authorize`, use uma função com `isSystemActor(ctx)`: a expressão em string não o reconhece, e
+   `ctx.provenance` não prova que a chamada veio de um schedule.
 3. Executa os `loads`, que carregam os dados usados na autorização.
 4. Avalia `authorize`, se houver: `false` vira `auth.forbidden`, e um `ActionError` devolvido é
    lançado como está.

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

@@ -23,7 +23,8 @@ interface DomainEvent<T = unknown> {
   actor: { id: string | null; type?: 'user' | 'system' | 'integration' }
   tenant?: string | null
   data: T
-  source: { action: string; actionId: string; correlation?: string }
+  source: { action: string; actionId: string; correlation?: string } // action que iniciou a cadeia
+  cause?: { reaction: string; eventId: string; eventType: string; depth: number } // só se publicado por reaction
   trace?: TraceContext                           // trace da execução que emitiu
   meta?: Record<string, unknown>                 // o terceiro argumento de ctx.emit
 }
@@ -105,17 +106,114 @@ com `runtime.eventbus_required` quando ele não existe. `defineReaction` declara
 quando não há separação entre cliente e servidor.
 
 A reaction roda com provenance `reaction`; `ctx.user` traz somente o `id` do autor do evento, e
-`ctx.tenantId`, o tenant do evento. O contexto não tem `can`: a decisão fica no `authorize(ctx, event)` opcional, e uma resposta `false` descarta o evento
-sem erro. Uma falha no handler é registrada no log e não chega à action que emitiu.
+`ctx.tenantId`, o tenant do evento. O contexto não tem `can`: a decisão fica no
+`authorize(ctx, event)` opcional, e uma resposta `false` descarta o evento sem erro. Uma falha na
+reaction fica no log e no audit e não chega à action que emitiu.
 
-## Limites atuais
+## Proteger a entrega
+
+Uma reaction costuma falar com algo que falha ou demora: uma API externa, uma fila, outro banco. A
+política de entrega, declarada no binding, diz como o runtime lida com isso:
+
+```ts
+export const leadSincronizarImpl = bindReaction(leadSincronizar, {
+  retry: { attempts: 3, backoff: { kind: 'exponential', initialMs: 1_000, maxMs: 30_000 } },
+  timeout: 10_000,
+  dedup: (event) => event.data.leadId,
+  concurrency: 2,
+  handler: async (ctx, event) => {
+    await crm.upsertLead(event.data.leadId, { signal: ctx.signal })
+  },
+})
+```
+
+O runtime aplica cada campo a cada evento entregue, nesta ordem:
+
+- **`dedup`** calcula uma chave para o evento. Outro evento com a mesma chave é descartado enquanto
+  o primeiro está na fila ou em andamento e durante `config.dedupCacheTtl` depois de ele concluir
+  (padrão de 60 segundos). Se a entrega falhar em definitivo, a chave é liberada, e o evento pode ser
+  entregue de novo. Cada reaction guarda no máximo `config.dedupCacheMaxEntries` chaves concluídas
+  (padrão 10.000); acima disso, a mais antiga sai antes do TTL, e um evento com ela volta a ser
+  aceito.
+- **`concurrency`** limita quantos eventos da reaction rodam ao mesmo tempo. O padrão é 1: sem
+  declarar, a reaction processa um evento por vez, na ordem de chegada. Acima disso,
+  `config.maxConcurrentReactions` (padrão 10) limita a soma de todas as reactions do processo. Com o
+  padrão, um handler sem `timeout` que trava — uma chamada de rede sem resposta, por exemplo —
+  segura a única vaga, e a reaction inteira para de processar eventos até o processo reiniciar.
+  Declare `timeout` em toda reaction que depende de algo externo.
+- **`authorize`**, quando declarado, roda uma vez, antes da primeira tentativa.
+- **`timeout`** é o prazo de cada tentativa, em milissegundos. Ao vencer, o runtime aborta
+  `ctx.signal` e encerra a tentativa com `runtime.reaction_timeout`. Passe o sinal adiante, como no
+  exemplo: um handler que o ignora continua executando em segundo plano, fora do limite de
+  concorrência.
+- **`retry`** repete o handler que falhou. `attempts` é o total de execuções, contando a primeira.
+  `fixed` espera `delayMs` entre elas; `exponential` começa em `initialMs`, multiplica por
+  `multiplier` (padrão 2) e para em `maxMs`. A espera entre tentativas não ocupa vaga de
+  concorrência.
+
+Uma exceção comum, como `throw new Error(...)`, e o `runtime.reaction_timeout` são sempre repetidos.
+Um `ActionError`, criado com `error()`, segue o próprio `retriable`, que por padrão vem da categoria:
+só `rate_limit` e `dependency` repetem; `validation`, `authentication`, `authorization`,
+`not_found`, `conflict` e `internal` encerram as tentativas. Para repetir um erro de outra categoria,
+declare-o ao criá-lo:
+
+```ts
+throw error({ code: 'crm.lead.locked', category: 'conflict', retriable: true })
+```
+
+Sem política declarada, o handler roda uma vez e um evento por vez. `config.defaultRetry` vale só
+para jobs em background, não para reactions. Com `retry`, o handler precisa tolerar a repetição: o
+`dedup` evita processar o mesmo evento duas vezes, mas não desfaz o que uma tentativa anterior
+já gravou. Declare também `timeout`: com a concorrência padrão, é ele que impede um handler travado
+de parar a reaction inteira.
+
+Cada tentativa que falha e será repetida gera o aviso `runtime.reaction_retry` no log, e a falha
+definitiva, a linha `reaction failed` com o número de tentativas. Um evento descartado pelo `dedup`
+gera uma linha `debug` com `runtime.reaction_duplicate_skipped`. Valores fora do domínio, como
+`concurrency: 0`, interrompem o registro com `runtime.invalid_reaction_policy`.
 
-O driver `mitt` funciona no mesmo processo, sem durabilidade nem entrega entre processos.
+Cada entrega que chega ao handler gera um registro de [auditoria](/docs/audit): `action` traz o
+nome da reaction, `meta` traz `{ kind: 'reaction', attempts }` e `input` traz só a identidade do
+evento (`id`, `type` e `source`). O payload fica no registro da action que emitiu, com a redação
+dela. Um evento recusado pelo `authorize` ou descartado pelo `dedup` não gera registro.
+
+## Encadear reactions
+
+Quando o efeito de uma reaction é um fato que outra parte do sistema precisa saber, ela o publica
+com `ctx.emit`, como uma action. A reaction declara no binding os eventos que publica:
+
+```ts
+export const leadSincronizarImpl = bindReaction(leadSincronizar, {
+  emits: ['lead.sincronizado'],
+  handler: async (ctx, event) => {
+    const externo = await crm.upsertLead(event.data.leadId)
+    await ctx.emit('lead.sincronizado', { leadId: event.data.leadId, externoId: externo.id })
+  },
+})
+```
+
+Diferente de uma action, uma reaction só publica o que está em `emits`. Um evento fora da lista,
+inclusive de uma reaction sem `emits`, é descartado, e o runtime registra o aviso
+`runtime.reaction_emit_ignored` com a reaction, o evento e a lista declarada. O aviso vem de
+`config.warnUndeclaredEmits`, ativo por padrão fora de produção.
+
+O evento publicado mantém `actor`, `tenant` e `source` do evento que a reaction processava: `source`
+continua apontando para a action que iniciou a cadeia. O campo `cause` registra a reaction que
+publicou, o evento de origem e a profundidade na cadeia, que começa em 1. Evento emitido por action
+não tem `cause`.
+
+Uma cadeia pode dar até `config.maxReactionDepth` saltos de reaction (padrão 5). O limite impede que
+um laço, como uma reaction que publica um evento que volta a acioná-la, consuma o processo. O
+`ctx.emit` que passaria do limite não publica e registra o erro `runtime.reaction_chain_too_deep`
+com a cadeia observada. Com `emitMode: 'strict'`, o mesmo código também interrompe a reaction.
+
+O manifest projeta o `emits` de cada reaction, e o [`opus introspect`](/docs/cli) liga esse `emits`
+às reactions que escutam o evento.
+
+## Limites atuais
 
-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, com o
-nome da reaction e do evento; em produção, o descarte continua silencioso. Quando outro consumidor
-precisa desse fato, emita o evento no handler da action que o produz e declare-o em `emits`.
+O driver `mitt` funciona no mesmo processo, sem durabilidade nem entrega entre processos. As
+políticas de entrega também 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 de concorrência, e um evento que
+espera vaga se perde se o processo cair.
 
-`retry`, `timeout`, `dedup` e `concurrency` são aceitos na declaração, mas o runtime ainda não os
-aplica: uma reaction que falha não é repetida.

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

@@ -41,8 +41,10 @@ subdomínios; um nome repetido de action, reaction, schedule ou Produto de Dados
 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).
+schedules sem `scheduler` (`runtime.scheduler_required`), e quando um schedule ativo aponta para uma
+action não registrada (`runtime.schedule_action_not_found`) ou que não aceita execução pelo sistema
+(`runtime.schedule_action_not_automatable`); veja [Agendador](/docs/scheduler). A declaração de um
+domínio está em [Actions & contratos](/docs/actions).
 
 ## As capacidades
 
@@ -122,6 +124,13 @@ Duas formas de código rodam sem uma requisição: um evento de domínio dispara
 [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.
 
+O runtime aplica a cada reaction a política de entrega declarada — `retry`, `timeout`, `dedup` e
+`concurrency` — e limita as execuções simultâneas de todas elas com `config.maxConcurrentReactions`
+(padrão 10). Uma reaction publica os eventos que declara em `emits`, e a cadeia para em
+`config.maxReactionDepth` saltos (padrão 5). O schedule executa a action como o sistema, sem
+usuário, quando o contrato dela declara `automatable: true`; `isSystemActor(ctx)` identifica essa
+execução no `authorize` e no handler.
+
 `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

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

@@ -5,8 +5,8 @@ title: Agendador
 # Agendador
 
 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.
+`SchedulerAdapter` registra o agendamento, e o runtime executa a action como o sistema, com
+provenance `schedule`, que aparece no audit e no contexto do handler.
 
 ## O contrato
 
@@ -47,7 +47,7 @@ Declare o schedule com `defineSchedule` e registre-o no domínio, ao lado da act
 
 ```ts
 import { createRuntime, defineDomain, defineSchedule } from '@softize/opus/core'
-import { caixaFechar } from './caixa-fechar.ts' // a action 'caixa.fechar', definida com bindAction
+import { caixaFechar } from './caixa-fechar.ts' // a action 'caixa.fechar', preparada abaixo
 
 const fecharDia = defineSchedule({
   name: 'caixa.fechar-dia',
@@ -71,22 +71,63 @@ await runtime.start()
 ```
 
 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
+e que aceita execução pelo sistema, e depois o registra no adapter. As duas conferências acontecem
+antes de inicializar os adapters, e cada mensagem lista os schedules e as actions afetadas. Um nome
+sem action registrada interrompe o `start()` com `runtime.schedule_action_not_found`; uma action
+sem `automatable` nem `public`, com `runtime.schedule_action_not_automatable` (veja a próxima
+seção). 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.
+O schedule executa a action como o sistema, sem uma pessoa por trás. Uma action que exige usuário
+recusa o sistema até que o contrato dela aceite essa execução com `automatable: true`:
+
+```ts
+import { defineContract, isSystemActor } from '@softize/opus/core'
+
+export const caixaFecharContract = defineContract({
+  name: 'caixa.fechar',
+  kind: 'simple',
+  input: z.object({}),
+  output: z.object({ fechados: z.number() }),
+  automatable: true,
+})
+
+export const caixaFechar = bindAction(caixaFecharContract, {
+  // O sistema não tem permissões: aceite-o de forma explícita ao lado da regra das pessoas.
+  authorize: (ctx) => isSystemActor(ctx) || ctx.can('caixa:fechar'),
+  handler: async (ctx) => ({ fechados: await caixa.fecharDia() }),
+})
+```
+
+`automatable` só vale para o disparo de um schedule. A action continua exigindo usuário em
+qualquer outra chamada: uma requisição HTTP sem usuário recebe `auth.unauthenticated`, como antes,
+mesmo que informe uma provenance `schedule`.
+
+Na execução pelo sistema, `ctx.user` é `null`, `ctx.can` nega toda permissão e `ctx.provenance` é
+`{ kind: 'schedule', scheduleName }`. `isSystemActor(ctx)` responde `true` só quando o próprio
+runtime criou essa execução, a partir de um schedule ou do job em background que ele enfileirou; o
+job leva a identidade em uma marca que o runtime grava no envelope, e não pela provenance. Uma tool
+que a action agendada chama por `ctx.ai` não herda a identidade.
+
+Aceite o sistema no `authorize` escrito como função, com `isSystemActor(ctx)`, como no exemplo. Um
+`authorize` em string, como `'user.role == "admin"'`, não tem como reconhecer o sistema: para uma
+action agendada com autorização própria, use a função. Não teste `ctx.provenance.kind` para esse
+fim: qualquer código do servidor que chama `runtime.execute` pode preencher a provenance com
+`schedule`. Sem `authorize`, `automatable` basta. O audit registra o ator como
+`{ id: null, type: 'system' }`, com o nome do schedule na provenance.
+
+Um schedule ativo que aponta para uma action sem `automatable` e sem `public` impede o `start()` com
+`runtime.schedule_action_not_automatable`. Para resolver, declare `automatable: true` no contrato da
+action ou, se o agendamento não deve rodar neste ambiente, `enabled: false` no schedule. Uma action
+`public: true` continua podendo ser agendada, mas fica aberta a qualquer chamador; prefira
+`automatable`.
 
 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,
+novo. Uma falha dentro do pipeline da action, como um erro do `authorize` ou 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`.
 

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

@@ -12,8 +12,8 @@ autorização. `@softize/opus/testing` executa esse fluxo em unidade, sem montar
 `runAction` segue a ordem do runtime: valida a entrada, exige usuário quando a action não é
 `public`, avalia `authorize`, executa o handler e valida a saída. Em `list`, a validação da saída é
 pulada, porque o schema descreve o item e o handler devolve a página. Falhas usam o mesmo
-`ActionError` tipado do runtime, como `validation.invalid_input`, `auth.unauthenticated` e
-`auth.forbidden`.
+`ActionError` tipado do runtime, como `validation.invalid_input`, `auth.unauthenticated`,
+`auth.system_forbidden` e `auth.forbidden`.
 
 Passe a action ligada ao handler, produzida por `bindAction`. O contrato puro não tem handler e só
 executa em modo design, descrito abaixo.
@@ -59,10 +59,22 @@ opcionais.
 | `ai` | Adapter de IA entregue em `ctx.ai`. Sem runtime, `run` e `runStream` não recebem tools. |
 | `meta`, `trace` | Valores de `ctx.meta` e `ctx.trace`. |
 | `loaded` | Substitui os loaders e chega ao `authorize` e ao handler. |
+| `schedule` | Executa como o sistema, no disparo do schedule com esse nome: ignora `user` e `can`. |
 
 `requires` é declarativo também no harness: nada o executa. Um handler que chama `ctx.can` recebe a
 resposta da opção `can`.
 
+Para uma action agendada, a opção `schedule` reproduz a execução pelo sistema com a mesma regra do
+runtime: `ctx.user` é `null`, `ctx.can` nega tudo e `isSystemActor(ctx)` responde `true`. Sem
+`automatable: true` no contrato, a action falha com `auth.system_forbidden`:
+
+```ts
+it('o fechamento diário roda pelo sistema', async () => {
+  const { output } = await runAction(caixaFechar, {}, { schedule: 'caixa.fechar-dia' })
+  expect(output.fechados).toBeGreaterThan(0)
+})
+```
+
 ## Observar efeitos
 
 `runAction` devolve, além de `output`, os efeitos capturados: `emitted` guarda cada `ctx.emit` e