@softize/opus 13.0.0 → 13.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softize/opus",
-  "version": "13.0.0",
+  "version": "13.1.0",
   "description": "End-to-end action protocol for TypeScript. Single package with subpath exports (core + adapters).",
   "license": "MIT",
   "type": "module",
@@ -202,6 +202,7 @@
     "docs",
     "README.md",
     "CHANGELOG.md",
+    "PROMOTED.md",
     "LICENSE"
   ],
   "publishConfig": {
@@ -259,7 +260,8 @@
     "node-cron": "^3.0.0",
     "pg": "^8.0.0",
     "pino": "^9.0.0",
-    "react": "^18.0.0 || ^19.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
     "react-hook-form": "^7.0.0",
     "vite": "^5.0.0 || ^6.0.0",
     "zod": "^3.24.0"
@@ -301,6 +303,9 @@
     "react": {
       "optional": true
     },
+    "react-dom": {
+      "optional": true
+    },
     "vite": {
       "optional": true
     },
@@ -328,7 +333,6 @@
     "@tanstack/react-query": "^5.62.0",
     "@testing-library/dom": "^10.4.0",
     "@testing-library/react": "^16.1.0",
-    "@types/better-sqlite3": "^7.6.0",
     "@types/jsonwebtoken": "^9.0.0",
     "@types/node": "^22.0.0",
     "@types/node-cron": "^3.0.0",

package/registry/templates/app/package.json

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

package/registry/templates/app/src/main.tsx

@@ -1,13 +1,13 @@
 import { StrictMode } from 'react'
 import { createRoot } from 'react-dom/client'
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
-import { TbdlibProvider, TooltipProvider } from '@softize/opus/ui/react'
+import { OpusProvider, TooltipProvider } from '@softize/opus/ui/react'
 import { fetchClient } from '@softize/opus/client/fetch'
 import { App } from './App.tsx'
 import './index.css'
 
 // O trio de providers do padrão da casa — os hooks (useTriggerAction/useFormAction…)
-// exigem QueryClient + Tbdlib, e qualquer Tooltip da base exige o TooltipProvider.
+// exigem QueryClient + OpusProvider, e qualquer Tooltip da base exige o TooltipProvider.
 const queryClient = new QueryClient()
 // Same-origin (/api). Quando o app ganhar server próprio, aponte o baseUrl pra ele.
 const client = fetchClient({ baseUrl: '' })
@@ -15,11 +15,11 @@ const client = fetchClient({ baseUrl: '' })
 createRoot(document.getElementById('root')!).render(
   <StrictMode>
     <QueryClientProvider client={queryClient}>
-      <TbdlibProvider client={client}>
+      <OpusProvider client={client}>
         <TooltipProvider>
           <App />
         </TooltipProvider>
-      </TbdlibProvider>
+      </OpusProvider>
     </QueryClientProvider>
   </StrictMode>,
 )

package/src/audit/drivers/console.ts

@@ -40,6 +40,7 @@ export interface ConsoleAuditOptions {
   redact?: (value: unknown) => unknown
 }
 
+/** Sink de auditoria que imprime cada registro no console, com redação opcional de campos sensíveis. */
 export function consoleAudit(options: ConsoleAuditOptions = {}): AuditSink {
   const {
     format = defaultFormat(),

package/src/auth/drivers/better-auth.ts

@@ -40,6 +40,7 @@ export interface BetterAuthDriverOptions {
 
 const denyAll: CanFn = () => false
 
+/** AuthAdapter que valida a sessão no IdP better-auth (`/api/auth/get-session`) com o cookie da request. */
 export function betterAuthSession(options: BetterAuthDriverOptions): AuthAdapter {
   const { baseURL, mapUser, mapTenant, can, timeoutMs = 5000, name = 'better-auth' } = options
   const base = baseURL.replace(/\/+$/, '')

package/src/auth/drivers/jwt.ts

@@ -79,6 +79,7 @@ export interface JwtAuthOptions<P extends JwtPayload = JwtPayload> {
 // Adapter factory
 // =============================================================================
 
+/** AuthAdapter que verifica um JWT (Bearer) e projeta o payload em `User` + `can`. */
 export function jwtAuth<P extends JwtPayload = JwtPayload>(
   options: JwtAuthOptions<P>,
 ): AuthAdapter {

package/src/cache/drivers/memory.ts

@@ -31,6 +31,7 @@ export interface MemoryCache extends CacheAdapter {
   size(): number
 }
 
+/** CacheAdapter em memória do processo, com TTL por entrada e limite opcional de itens; adequado a dev e testes. */
 export function memoryCache(options: MemoryCacheOptions = {}): MemoryCache {
   const entries = new Map<string, Entry>()
   const maxEntries = options.maxEntries ?? 10_000

package/src/client/drivers/fetch.ts

@@ -50,6 +50,7 @@ export interface FetchClientOptions {
 // Adapter factory
 // =============================================================================
 
+/** ClientAdapter que chama actions via HTTP `fetch`, classificando falhas de transporte como `dependency`. */
 export function fetchClient(options: FetchClientOptions): ClientAdapter {
   const {
     baseUrl,
@@ -92,7 +93,7 @@ export function fetchClient(options: FetchClientOptions): ClientAdapter {
           error({
             code: 'client.network',
             category: 'dependency',
-            message: 'Network request failed',
+            message: `Falha de rede ao chamar ${action.name}`,
             cause: String(cause),
           }),
         )

package/src/core/actions.ts

@@ -1,9 +1,14 @@
 /**
- * tbdlib — `defineAction` factory + type guards
+ * Opus — `defineAction` factory + type guards
  *
  * `defineAction` é identity function tipada que aceita qualquer variante
  * de `ActionDef` e preserva o subtipo exato pra type narrowing posterior.
  *
+ * Quando cliente e servidor consomem a mesma action, o caminho canônico é
+ * `defineContract` (parte compartilhável) + `bindAction` (handler, loads e o
+ * resto server-only) — ver `contracts.ts`. `defineAction` continua válido e
+ * suportado para action server-only, em que não há contrato a compartilhar.
+ *
  * Validação estrutural acontece no `Runtime.register()`, não aqui. Esta função
  * é puramente sobre **declaração**.
  *

package/src/core/audit.ts

@@ -1,5 +1,5 @@
 /**
- * tbdlib — AuditEmitter
+ * Opus — AuditEmitter
  *
  * Classe que coordena a emissão de `AuditRecord` pros `AuditSink` registrados.
  * Aplica config da action (redact, fields, severity, sink filter) antes de
@@ -71,11 +71,17 @@ export class AuditEmitter {
     if (failures.length === 0) return
 
     if (this.mode === 'strict') {
+      this.log.error('audit sinks failed (strict mode)', {
+        failures: failures.length,
+        total: targetSinks.length,
+        reasons: failures.map((f) => String(f.reason)),
+      })
       throw error({
         code: 'audit.sink.failed',
         category: 'internal',
-        message: `${failures.length}/${targetSinks.length} audit sinks failed`,
-        meta: { failures: failures.map((f) => String(f.reason)) },
+        message: `${failures.length} de ${targetSinks.length} sinks de auditoria falharam`,
+        // Só o número vai à wire; o motivo cru de cada sink fica no log do servidor.
+        meta: { failures: failures.length },
       })
     }
 

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>
 

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()