@softize/opus 13.0.0 → 14.0.0

package/src/core/contracts.ts

@@ -64,6 +64,7 @@ export type ViewContract<In = unknown, Out = unknown, ParsedIn = any> = Omit<
   BindingKeys
 >
 
+/** União dos contratos por kind — o que `bindAction` aceita e a UI tipada consome. */
 export type ActionContract<In = any, Out = any, ParsedIn = any> =
   | SimpleContract<In, Out, ParsedIn>
   | FormContract<In & Record<string, unknown>, Out, ParsedIn>
@@ -97,6 +98,12 @@ export interface ActionBinding<ParsedIn, Out> {
 // defineContract (overloads por kind, igual defineAction)
 // =============================================================================
 
+/**
+ * Declara a parte compartilhável de uma action (identidade, schemas, docs e
+ * `authorize` action-level) sem handler nem dependência server-only — pode
+ * ser importada pelo cliente. Identity function tipada; o kind é inferido
+ * pelo overload. Complete com `bindAction` no servidor.
+ */
 export function defineContract<In, Out, ParsedIn = In>(
   contract: SimpleContract<In, Out, ParsedIn>,
 ): SimpleContract<In, Out, ParsedIn>

package/src/core/domain.ts

@@ -1,5 +1,5 @@
 /**
- * tbdlib — `defineDomain` factory + flatten helper.
+ * Opus — `defineDomain` factory + flatten helper.
  *
  * Domain agrupa as peças que pertencem a um mesmo recorte funcional
  * (dicts, entities, repository, service, actions, reactions, schedules,

package/src/core/errors.ts

@@ -1,5 +1,5 @@
 /**
- * tbdlib — Error factory
+ * Opus — Error factory
  *
  * `error()` é a maneira canônica de emitir `ActionError` de dentro de um handler.
  * Aplica defaults sensatos baseados na categoria (severity, retriable) e
@@ -9,11 +9,12 @@
  *   throw error({
  *     code: 'deal.archive.notFound',
  *     category: 'not_found',
- *     message: `Deal ${id} not found`,
+ *     message: `Negócio ${id} não encontrado`,
  *   })
  *
  * Erros não criados via `error()` (ex: `throw new Error(...)`, exceções de driver)
- * são normalizados pelo runtime em `{ category: 'internal', code: 'internal.unhandled' }`.
+ * são normalizados pelo runtime em `{ category: 'internal', code: 'internal.unhandled' }`
+ * com a microcopy fixa `UNHANDLED_ERROR_MESSAGE`; o texto original vai só para `cause`.
  */
 
 import type {
@@ -24,7 +25,7 @@ import type {
 } from './types.ts'
 
 /** Brand interno pra distinguir ActionError construído via `error()` de Error genérico. */
-const ACTION_ERROR_BRAND = Symbol('tbdlib.ActionError')
+const ACTION_ERROR_BRAND = Symbol('opus.ActionError')
 
 /**
  * Defaults de severity por categoria.
@@ -148,27 +149,29 @@ export function isActionError(value: unknown): value is ActionError {
   )
 }
 
+/**
+ * Microcopy que a pessoa recebe quando um handler falha com exceção não tratada.
+ * Fixa de propósito: a mensagem crua (driver, SQL, stack) fica no logger do
+ * runtime e em `cause`, nunca vira o texto exibido.
+ */
+export const UNHANDLED_ERROR_MESSAGE =
+  'Não foi possível concluir a operação. Tente novamente.'
+
 /**
  * Normaliza uma exceção qualquer em ActionError. Usado pelo runtime quando
  * handler lança algo que não foi criado via `error()`.
+ *
+ * A `message` é sempre `UNHANDLED_ERROR_MESSAGE`; o valor lançado é preservado
+ * em `cause` (só a mensagem quando for `Error` — stack não vaza pra wire).
  */
 export function normalizeError(thrown: unknown): ActionError {
   if (isActionError(thrown)) return thrown
 
-  if (thrown instanceof Error) {
-    return error({
-      code: 'internal.unhandled',
-      category: 'internal',
-      message: thrown.message,
-      cause: thrown.message, // só mensagem; stack não vaza pra wire
-    })
-  }
-
   return error({
     code: 'internal.unhandled',
     category: 'internal',
-    message: typeof thrown === 'string' ? thrown : 'Unhandled error',
-    cause: thrown,
+    message: UNHANDLED_ERROR_MESSAGE,
+    cause: thrown instanceof Error ? thrown.message : thrown,
   })
 }
 

package/src/core/index.ts

@@ -1,7 +1,9 @@
 /**
  * @softize/opus/core — public entry
  *
- * Re-exports da superfície pública. Source of truth: `/docs/protocol.md`.
+ * Re-exports da superfície pública. A fonte de verdade são as declarações
+ * (`defineContract`, `bindAction`, `defineDomain`…); `/docs/protocol.md`, o
+ * manifest e o OpenAPI são projeções delas.
  */
 
 // — Tipos —————————————————————————————————————————————————————————————————————
@@ -128,7 +130,7 @@ export type {
 } from './types.ts'
 
 // — Erro ——————————————————————————————————————————————————————————————————————
-export { error, isActionError, normalizeError } from './errors.ts'
+export { error, isActionError, normalizeError, UNHANDLED_ERROR_MESSAGE } from './errors.ts'
 export type { ErrorInput } from './errors.ts'
 export { normalizeTraceContext } from './trace.ts'
 

package/src/core/package-version.ts

@@ -0,0 +1,26 @@
+/**
+ * Opus — versão do pacote lida do `package.json` que viaja junto do source.
+ *
+ * Server-only (usa `node:fs`); não é re-exportado por `core/index.ts`. Usado
+ * pelos drivers de servidor (info do OpenAPI), pelo servidor MCP e pelo plugin
+ * de design pra identificar a versão do SDK sem duplicar leitura de arquivo.
+ */
+
+import { readFileSync } from 'node:fs'
+
+const FALLBACK_VERSION = '0.0.0'
+
+/** Versão de `@softize/opus` resolvida do `package.json` real; `0.0.0` se a leitura falhar. */
+export function readPackageVersion(): string {
+  // `import.meta.url` sobrevive ao bundling do vite.config (o vite injeta a
+  // URL original do arquivo), então o package.json resolve do source real.
+  try {
+    const pkg = JSON.parse(
+      readFileSync(new URL('../../package.json', import.meta.url), 'utf8'),
+    ) as { version?: string }
+    return pkg.version ?? FALLBACK_VERSION
+    /* v8 ignore next 3 — defensivo; o package.json viaja junto do source */
+  } catch {
+    return FALLBACK_VERSION
+  }
+}

package/src/core/reactions.ts

@@ -1,5 +1,5 @@
 /**
- * tbdlib — `defineReaction` factory + type guards
+ * Opus — `defineReaction` factory + type guards
  *
  * `defineReaction` é identity function tipada que aceita uma `ReactionDef`
  * e preserva o tipo do evento pra inferência. Runtime registra no

package/src/core/runtime.ts

@@ -1,5 +1,5 @@
 /**
- * tbdlib — Runtime
+ * Opus — Runtime
  *
  * Orquestrador central. Recebe actions + reactions + adapters + config no setup,
  * registra cada peça, e executa o pipeline padrão (validate → load → auth →
@@ -281,7 +281,7 @@ export class Runtime {
     this.config = applyConfigDefaults(setup.config)
     this.logger = setup.logger
     this.observability = setup.observability
-    this.log = setup.logger ?? new ConsoleLogger({ runtime: 'tbdlib' })
+    this.log = setup.logger ?? new ConsoleLogger({ runtime: 'opus' })
 
     this.audit = new AuditEmitter({ mode: this.config.auditMode, log: this.log })
     if (setup.audit !== undefined) {
@@ -345,7 +345,7 @@ export class Runtime {
         throw error({
           code: 'runtime.duplicate_loader',
           category: 'internal',
-          message: `Loader resolver "${entity}" already registered`,
+          message: `Já existe um resolver de loader registrado para "${entity}"`,
         })
       }
       this.loaderResolvers.set(entity, resolver)
@@ -368,7 +368,7 @@ export class Runtime {
         throw error({
           code: 'runtime.duplicate_action',
           category: 'internal',
-          message: `Action "${action.name}" registered twice`,
+          message: `Action "${action.name}" registrada duas vezes`,
         })
       }
       this.actions.set(action.name, action)
@@ -381,7 +381,7 @@ export class Runtime {
         throw error({
           code: 'runtime.duplicate_reaction',
           category: 'internal',
-          message: `Reaction "${reaction.name}" registered twice`,
+          message: `Reaction "${reaction.name}" registrada duas vezes`,
         })
       }
       this.reactions.set(reaction.name, reaction)
@@ -394,7 +394,7 @@ export class Runtime {
         throw error({
           code: 'runtime.duplicate_schedule',
           category: 'internal',
-          message: `Schedule "${schedule.name}" registered twice`,
+          message: `Schedule "${schedule.name}" registrado duas vezes`,
         })
       }
       this.schedules.set(schedule.name, schedule)
@@ -410,7 +410,7 @@ export class Runtime {
       throw error({
         code: 'runtime.already_started',
         category: 'internal',
-        message: 'Runtime.start() called twice',
+        message: 'Runtime.start() foi chamado mais de uma vez',
       })
     }
 
@@ -431,7 +431,7 @@ export class Runtime {
       throw error({
         code: 'runtime.eventbus_required',
         category: 'internal',
-        message: `${this.reactions.size} reaction(s) registered without an EventBusAdapter`,
+        message: `${this.reactions.size} reaction(s) registrada(s) sem um EventBusAdapter configurado`,
       })
     }
 
@@ -441,7 +441,7 @@ export class Runtime {
       throw error({
         code: 'runtime.scheduler_required',
         category: 'internal',
-        message: `${this.schedules.size} schedule(s) registered without a SchedulerAdapter`,
+        message: `${this.schedules.size} schedule(s) registrado(s) sem um SchedulerAdapter configurado`,
       })
     }
 
@@ -514,7 +514,7 @@ export class Runtime {
       return this.errorResult(actionName, error({
         code: 'runtime.action_not_found',
         category: 'not_found',
-        message: `Action "${actionName}" is not registered`,
+        message: `Action "${actionName}" não está registrada`,
       }), 0, ctxBase.requestId)
     }
 
@@ -535,21 +535,21 @@ export class Runtime {
       return this.errorResult(spec.action, error({
         code: 'runtime.action_not_found',
         category: 'not_found',
-        message: `Action "${spec.action}" is not registered`,
+        message: `Action "${spec.action}" não está registrada`,
       }), 0, spec.ctx.requestId)
     }
     if (!isBackgroundAction(action)) {
       return this.errorResult(spec.action, error({
         code: 'runtime.action_not_background',
         category: 'validation',
-        message: `Action "${spec.action}" is not declared as background`,
+        message: `Action "${spec.action}" não está declarada como background`,
       }), 0, spec.ctx.requestId)
     }
     if ((ctxBase.user?.id ?? null) !== spec.ctx.userId) {
       return this.errorResult(spec.action, error({
         code: 'runtime.job_actor_mismatch',
         category: 'authentication',
-        message: 'Worker context actor does not match the job envelope',
+        message: 'O ator do contexto do worker não corresponde ao envelope do job',
       }), 0, spec.ctx.requestId)
     }
 
@@ -604,7 +604,7 @@ export class Runtime {
         throw error({
           code: 'auth.unauthenticated',
           category: 'authentication',
-          message: 'Authentication required',
+          message: 'Autenticação necessária',
         })
       }
 
@@ -616,7 +616,7 @@ export class Runtime {
           throw error({
             code: 'auth.forbidden',
             category: 'authorization',
-            message: 'Forbidden',
+            message: 'Acesso negado',
           })
         }
         if (decision !== true) throw decision
@@ -627,7 +627,7 @@ export class Runtime {
           throw error({
             code: 'runtime.queue_required',
             category: 'internal',
-            message: `Background action "${action.name}" requires a QueueAdapter`,
+            message: `A action background "${action.name}" exige um QueueAdapter`,
           })
         }
         const background = action.background
@@ -635,7 +635,7 @@ export class Runtime {
           throw error({
             code: 'runtime.invalid_background_config',
             category: 'internal',
-            message: `Background action "${action.name}" has no background config`,
+            message: `A action background "${action.name}" não tem configuração de background`,
           })
         }
         const spec: JobSpec = {
@@ -729,6 +729,14 @@ export class Runtime {
         meta: this.buildMeta(actionId, action.name, durationMs, ctxBase.requestId, trace),
       }
         } catch (thrown) {
+      // Exceção fora de `error()` vira microcopy fixa no envelope; o texto
+      // original só sobrevive aqui, no logger da action, e em `cause`.
+      if (!isActionError(thrown)) {
+        ctx.log.error('action failed with unhandled error', {
+          error: thrown instanceof Error ? thrown.message : String(thrown),
+          ...(thrown instanceof Error && thrown.stack !== undefined ? { stack: thrown.stack } : {}),
+        })
+      }
       const actionError = normalizeError(thrown)
       const durationMs = performance.now() - startedAt
       await this.audit.emit(
@@ -898,7 +906,7 @@ export class Runtime {
           throw error({
             code: 'emit.no_bus',
             category: 'internal',
-            message: `ctx.emit('${event}') called without EventBusAdapter`,
+            message: `ctx.emit('${event}') chamado sem EventBusAdapter configurado`,
           })
         }
         this.log.warn('emit dropped — no EventBusAdapter', { event })
@@ -931,7 +939,7 @@ export class Runtime {
           throw error({
             code: 'emit.failed',
             category: 'internal',
-            message: `failed to publish event "${event}"`,
+            message: `Falha ao publicar o evento "${event}"`,
             cause: String(err),
           })
         }
@@ -953,7 +961,7 @@ export class Runtime {
     throw error({
       code: kind === 'input' ? 'validation.invalid_input' : 'validation.invalid_output',
       category: kind === 'input' ? 'validation' : 'internal',
-      message: kind === 'input' ? 'Input validation failed' : 'Output validation failed (dev)',
+      message: kind === 'input' ? 'Dados de entrada inválidos' : 'Dados de saída inválidos (validação em dev)',
       issues: result.issues.map((iss) => ({
         path: (iss.path ?? []).join('.'),
         code: 'invalid',
@@ -978,7 +986,7 @@ export class Runtime {
         throw error({
           code: `${action.name}.${key}.not_found`,
           category: 'not_found',
-          message: `Resource "${key}" not found for action "${action.name}"`,
+          message: `Recurso "${key}" não encontrado para a action "${action.name}"`,
         })
       }
       loaded[key] = value
@@ -1128,7 +1136,7 @@ export class Runtime {
       throw error({
         code: 'runtime.subscribe_unsupported',
         category: 'internal',
-        message: 'EventBusAdapter does not support subscribe()',
+        message: 'O EventBusAdapter não suporta subscribe()',
       })
     }
     const patterns = Array.isArray(reaction.on) ? reaction.on : [reaction.on]
@@ -1222,10 +1230,12 @@ export class Runtime {
       },
     )
     } catch (err) {
-      const actionError = isActionError(err) ? err : normalizeError(err)
+      const actionError = normalizeError(err)
       reactionLog.error('reaction failed', {
         code: actionError.code,
         message: actionError.message,
+        // Erro não tratado tem microcopy fixa; o texto original está em `cause`.
+        ...(actionError.cause !== undefined ? { cause: actionError.cause } : {}),
       })
     }
   }

package/src/core/schedules.ts

@@ -1,5 +1,5 @@
 /**
- * tbdlib — `defineSchedule` factory + type guards.
+ * Opus — `defineSchedule` factory + type guards.
  *
  * Schedule é a primitiva pra **ação iniciada pelo próprio sistema** — sem
  * trigger externo (HTTP, evento, AI). Usado pra monitoramento, relatórios,

package/src/core/types.ts

@@ -1,5 +1,5 @@
 /**
- * tbdlib — Core types
+ * Opus — Core types
  *
  * Tipos centrais do protocolo. Source of truth: `/docs/protocol.md`.
  * Qualquer divergência entre este arquivo e a doc é bug; alinhar a doc primeiro,
@@ -250,7 +250,7 @@ export interface User {
 
 /**
  * Função que checa permissão. Plugada pelo `AuthAdapter`.
- * tbdlib não implementa RBAC/ABAC — apenas delega.
+ * O Opus não implementa RBAC/ABAC — apenas delega.
  */
 export type CanFn = (permission: string, resource?: unknown) => boolean | Promise<boolean>
 
@@ -551,9 +551,8 @@ export type FieldWidget = BuiltInFieldWidget | (string & { readonly __opusCustom
 export interface FieldSpec {
   label: I18nRef
   placeholder?: I18nRef
-  hint?: I18nRef
-  /** Ajuda no hover/foco da label (ícone ⓘ + tooltip). `hint` = texto auxiliar SOB o campo;
-   *  `help` = explicação mais longa, escondida atrás do ícone na label. */
+  /** Ajuda junto à label (ícone ⓘ + tooltip): critério, efeito ou limitação que a label não
+   *  diz. Ajuda que só repete a label deve ser omitida. */
   help?: I18nRef
 
   default?: unknown
@@ -629,7 +628,7 @@ export interface ListColumnSpec {
    *  'badge' (chip `outline` com o valor — legado; coluna de dicionário com `presentation`
    *  declarado usa `DictionaryValue` e dispensa este tipo). */
   type?: 'text' | 'number' | 'date' | 'badge'
-  /** Referência do dicionário registrado em `TbdlibProvider dicts` que esta coluna mostra,
+  /** Referência do dicionário registrado em `OpusProvider dicts` que esta coluna mostra,
    *  quando o schema de saída não carrega a meta de `t.dict` (ex.: campo `z.string()`).
    *  Coluna cujo campo de saída É um `t.dict().zod()` resolve sozinha, sem esta chave. */
   dictionary?: string

package/src/dsl/eval.ts

@@ -64,7 +64,7 @@ export function evalExpression(node: AstNode, ctx: EvalContext): unknown {
           return (left as number) / (right as number)
         /* v8 ignore next 2 */
         default:
-          throw new Error(`DSL eval: unknown binary op ${node.op as string}`)
+          throw new Error(`DSL eval: operador binário desconhecido ${node.op as string}`)
       }
     }
     case 'in': {
@@ -132,5 +132,5 @@ function callFunction(name: string, args: unknown[]): unknown {
       }
       return null
   }
-  throw new Error(`DSL eval: unknown function '${name}'`)
+  throw new Error(`DSL eval: função desconhecida '${name}'`)
 }

package/src/dsl/kysely.ts

@@ -136,7 +136,7 @@ function compile(node: AstNode, eb: KyselyEb, bindings: KyselyBindings): any {
           return (left as number) / (right as number)
         /* v8 ignore next 2 */
         default:
-          throw new Error(`DSL kysely: unhandled binary ${node.op as string}`)
+          throw new Error(`DSL kysely: operador binário não tratado ${node.op as string}`)
       }
     }
     case 'in': {
@@ -195,7 +195,7 @@ function compile(node: AstNode, eb: KyselyEb, bindings: KyselyBindings): any {
             `DSL kysely: function '${node.name}' precisa de mapping de coluna explícito (use eb.fn)`,
           )
       }
-      throw new Error(`DSL kysely: unknown function '${node.name}'`)
+      throw new Error(`DSL kysely: função desconhecida '${node.name}'`)
     }
   }
 }

package/src/dsl/loads.ts

@@ -31,7 +31,7 @@ export function parseLoad(src: string): LoadSpec {
   const trimmed = src.trim()
   const m = LOAD_RE.exec(trimmed)
   if (m === null) {
-    throw new Error(`DSL loads: invalid syntax '${src}'`)
+    throw new Error(`DSL loads: sintaxe inválida '${src}'`)
   }
   const entity = m[1]!
   const argsRaw = m[2]!.trim()

package/src/dsl/parser.ts

@@ -89,7 +89,7 @@ function tokenize(src: string): Token[] {
         }
       }
       if (i >= src.length) {
-        throw new Error(`DSL parse error: unterminated string at ${startPos}`)
+        throw new Error(`DSL parse: string não terminada na posição ${startPos}`)
       }
       i += 1 // skip closing quote
       tokens.push({ type: 'STRING', value: val, pos: startPos })
@@ -150,7 +150,7 @@ function tokenize(src: string): Token[] {
     }
 
     throw new Error(
-      `DSL parse error: unexpected character '${c}' at position ${i}`,
+      `DSL parse: caractere inesperado '${c}' na posição ${i}`,
     )
   }
   tokens.push({ type: 'EOF', value: '', pos: src.length })
@@ -184,7 +184,7 @@ class Parser {
     if (!this.match(type, value)) {
       const t = this.peek()
       throw new Error(
-        `DSL parse error: expected ${value ?? type}, got '${t.value}' at ${t.pos}`,
+        `DSL parse: esperado ${value ?? type}, recebido '${t.value}' na posição ${t.pos}`,
       )
     }
     return this.consume()
@@ -343,7 +343,7 @@ class Parser {
       const t = this.consume()
       const n = Number(t.value)
       if (Number.isNaN(n)) {
-        throw new Error(`DSL parse error: invalid number '${t.value}'`)
+        throw new Error(`DSL parse: número inválido '${t.value}'`)
       }
       return { kind: 'literal', value: n }
     }
@@ -409,7 +409,7 @@ class Parser {
     }
     const t = this.peek()
     throw new Error(
-      `DSL parse error: unexpected token '${t.value}' at ${t.pos}`,
+      `DSL parse: token inesperado '${t.value}' na posição ${t.pos}`,
     )
   }
 }

package/src/events/drivers/mitt.ts

@@ -39,6 +39,7 @@ export interface MittEventsOptions {
  */
 type EventMap = Record<string, DomainEvent>
 
+/** EventBusAdapter in-process baseado em `mitt`; entrega no mesmo processo, sem persistência. */
 export function mittEvents(options: MittEventsOptions = {}): EventBusAdapter {
   const { name = 'mitt' } = options
   const emitter: Emitter<EventMap> = mitt<EventMap>()

package/src/mcp/index.ts

@@ -13,6 +13,7 @@ import { Server } from '@modelcontextprotocol/sdk/server/index.js'
 import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js'
 import { zodToJsonSchema } from 'zod-to-json-schema'
 import type { ContextBase, Runtime } from '../core/index.ts'
+import { readPackageVersion } from '../core/package-version.ts'
 
 export interface OpusMcpOptions {
   name?: string
@@ -36,7 +37,7 @@ export function createOpusMcpServer(runtime: Runtime, opts: OpusMcpOptions = {})
     opts.toJsonSchema ?? ((schema: unknown) => zodToJsonSchema(schema as never, { $refStrategy: 'none' }))
 
   const server = new Server(
-    { name: opts.name ?? 'opus', version: opts.version ?? '0.0.0' },
+    { name: opts.name ?? 'opus', version: opts.version ?? readPackageVersion() },
     { capabilities: { tools: {} } },
   )
 

package/src/observability/drivers/opentelemetry.ts

@@ -40,6 +40,7 @@ export interface OpenTelemetryObservabilityOptions {
   healthCheck?: () => Promise<HealthStatus> | HealthStatus
 }
 
+/** ObservabilityAdapter que abre um span OpenTelemetry por action/reaction e propaga o trace context. */
 export function openTelemetryObservability(
   options: OpenTelemetryObservabilityOptions = {},
 ): ObservabilityAdapter {

package/src/queue/drivers/bullmq.ts

@@ -13,7 +13,7 @@
  *   import { Queue } from 'bullmq'
  *   import { bullmqQueue } from '@softize/opus/queue/bullmq'
  *
- *   const queue = new Queue('tbdlib-jobs', { connection: redisOpts })
+ *   const queue = new Queue('opus-jobs', { connection: redisOpts })
  *   createRuntime({ queue: bullmqQueue({ queue }) })
  */
 
@@ -139,9 +139,9 @@ function bullmqOptions(spec: JobSpec): BullMQAddOptions {
 // =============================================================================
 
 /**
- * BullMQ state → tbdlib JobStatus.
+ * BullMQ state → Opus JobStatus.
  *
- * tbdlib não tem 'paused' nem 'delayed' separados — todos viram 'queued'.
+ * O Opus não tem 'paused' nem 'delayed' separados — todos viram 'queued'.
  * Distinção fina fica no `details.meta.bullmqState` se consumer precisar.
  */
 export function mapState(state: BullMQState): JobStatus {

package/src/scheduler/drivers/node-cron.ts

@@ -31,6 +31,7 @@ export interface NodeCronOptions {
   onError?: (err: unknown, schedule: ScheduleDef) => void
 }
 
+/** SchedulerAdapter sobre `node-cron`; aceita `cron` ou o atalho `every` de cada schedule. */
 export function nodeCronScheduler(
   options: NodeCronOptions = {},
 ): SchedulerAdapter {
@@ -83,11 +84,11 @@ function resolveCron(spec: ScheduleDef): string {
   if (spec.cron !== undefined) return spec.cron
   if (spec.every !== undefined) return everyToCron(spec.every)
   throw new Error(
-    `Schedule "${spec.name}" must declare either 'cron' or 'every'.`,
+    `O schedule "${spec.name}" precisa declarar 'cron' ou 'every'.`,
   )
 }
 
 function defaultOnError(err: unknown, schedule: ScheduleDef): void {
   // eslint-disable-next-line no-console
-  console.error(`[tbdlib/scheduler] schedule "${schedule.name}" fire failed:`, err)
+  console.error(`[opus/scheduler] falha ao disparar o schedule "${schedule.name}":`, err)
 }

package/src/scheduler/every.ts

@@ -15,30 +15,30 @@ export function everyToCron(every: string): string {
   const match = /^(\d+)(s|m|h|d)$/.exec(every.trim())
   if (match === null) {
     throw new Error(
-      `Invalid 'every' shorthand: "${every}". ` +
-        `Expected formato "<n><s|m|h|d>" (ex: "15s", "5m", "1h", "1d").`,
+      `Atalho 'every' inválido: "${every}". ` +
+        `Formato esperado "<n><s|m|h|d>" (ex: "15s", "5m", "1h", "1d").`,
     )
   }
   const n = Number.parseInt(match[1] as string, 10)
   const unit = match[2] as 's' | 'm' | 'h' | 'd'
 
   if (n <= 0) {
-    throw new Error(`'every' value must be > 0, got "${every}".`)
+    throw new Error(`O valor de 'every' precisa ser maior que 0; recebido "${every}".`)
   }
 
   switch (unit) {
     case 's':
-      if (n > 59) throw new Error(`'every' seconds must be <= 59, got ${n}.`)
+      if (n > 59) throw new Error(`Segundos em 'every' precisam ser no máximo 59; recebido ${n}.`)
       return `*/${n} * * * * *`
     case 'm':
-      if (n > 59) throw new Error(`'every' minutes must be <= 59, got ${n}.`)
+      if (n > 59) throw new Error(`Minutos em 'every' precisam ser no máximo 59; recebido ${n}.`)
       return `*/${n} * * * *`
     case 'h':
-      if (n > 23) throw new Error(`'every' hours must be <= 23, got ${n}.`)
+      if (n > 23) throw new Error(`Horas em 'every' precisam ser no máximo 23; recebido ${n}.`)
       return n === 1 ? '0 * * * *' : `0 */${n} * * *`
     case 'd':
       if (n !== 1) {
-        throw new Error(`'every' days only supports 1d. For longer intervals use cron.`)
+        throw new Error(`Dias em 'every' aceitam somente 1d. Para intervalos maiores, use cron.`)
       }
       return '0 0 * * *'
   }

package/src/schema/openapi.ts

@@ -175,15 +175,15 @@ function buildResponses(
   const successStatus = String(action.successStatus ?? 200)
   const responses: Record<string, OpenAPIResponse> = {
     [successStatus]: {
-      description: 'Success',
+      description: 'Sucesso',
       content: {
         'application/json': {
           schema: wrapEnvelope(toJsonSchema(action.output), action.kind),
         },
       },
     },
-    '4XX': errorResponse('Client error', action.errors),
-    '5XX': errorResponse('Server error'),
+    '4XX': errorResponse('Erro do cliente', action.errors),
+    '5XX': errorResponse('Erro do servidor'),
   }
   return responses
 }