@softize/opus 8.6.6

package/registry/templates/monorepo/pnpm-workspace.yaml

@@ -0,0 +1,14 @@
+# Membros do monorepo: apps (produtos) em apps/*, libs compartilhadas em packages/*.
+packages:
+  - 'apps/*'
+  - 'packages/*'
+
+# Permissão de build scripts (o pnpm bloqueia por default): o postinstall do
+# @softize/opus roda o `opus setup` a cada install; o esbuild (vite) compila o binário.
+allowBuilds:
+  '@softize/opus': true
+  esbuild: true
+
+# A base é do nosso registry (confiada): fora da quarentena de release do pnpm.
+minimumReleaseAgeExclude:
+  - '@softize/opus'

package/src/ai/ask.ts

@@ -0,0 +1,64 @@
+/**
+ * Contrato de "perguntar à pessoa no meio do turno" (elicitação) — o ponto de CONSISTÊNCIA
+ * pra qualquer consumidor de IA do Opus. O driver reserva o nome `ask_user` e, com um
+ * `onAsk` (ver `AiRunOptions.onAsk`), faz o round-trip real; sem ele, recusa com erro
+ * acionável em vez de deixar a chamada morrer no vazio. Aqui vivem o nome reservado, o
+ * schema/descrição da tool e o formatador da resposta.
+ */
+import type { AskQuestion, AskAnswer } from '../core/index.ts'
+
+/** Nome reservado da tool de perguntar à pessoa — o driver a intercepta (ver `onAsk`). */
+export const ASK_USER_TOOL = 'ask_user'
+
+/** Descrição da tool — instrui o modelo a preferir isto a chutar. */
+export const ASK_TOOL_DESCRIPTION =
+  'Faça UMA rodada de perguntas de esclarecimento à pessoa e BLOQUEIE até ela responder. ' +
+  'Use quando faltar informação pra decidir (escopo, formato, obrigatoriedade) em vez de assumir. ' +
+  'Envie de 1 a 4 perguntas objetivas, cada uma com opções curtas; a ferramenta devolve as escolhas da pessoa.'
+
+/** JSON Schema do input do `ask_user` — fonte única (o driver injeta a tool com isto). */
+export const ASK_INPUT_SCHEMA = {
+  type: 'object',
+  properties: {
+    questions: {
+      type: 'array',
+      minItems: 1,
+      maxItems: 4,
+      description: 'De 1 a 4 perguntas objetivas de esclarecimento.',
+      items: {
+        type: 'object',
+        properties: {
+          question: { type: 'string', description: 'O enunciado da pergunta.' },
+          header: { type: 'string', description: 'Rótulo curto (1-2 palavras) que resume a pergunta.' },
+          multiSelect: { type: 'boolean', description: 'Permite marcar mais de uma opção.' },
+          options: {
+            type: 'array',
+            minItems: 2,
+            items: {
+              type: 'object',
+              properties: { label: { type: 'string' }, description: { type: 'string' } },
+              required: ['label'],
+            },
+          },
+        },
+        required: ['question', 'options'],
+      },
+    },
+  },
+  required: ['questions'],
+} as const
+
+/** Texto legível das respostas pro modelo consumir como resultado do tool. */
+export function formatAnswers(questions: AskQuestion[], answers: AskAnswer[]): string {
+  return questions
+    .map((q, i) => {
+      const a = answers[i]
+      const label = q.header !== undefined && q.header.length > 0 ? q.header : q.question
+      const picked = [
+        ...(a?.selected ?? []),
+        ...(a?.text !== undefined && a.text.trim().length > 0 ? [a.text.trim()] : []),
+      ]
+      return `${label}: ${picked.length > 0 ? picked.join(', ') : '(sem resposta)'}`
+    })
+    .join('\n')
+}

package/src/ai/drivers/anthropic.ts

@@ -0,0 +1,309 @@
+/**
+ * @softize/opus/ai/anthropic — driver Anthropic (EXPERIMENTAL).
+ *
+ * O consumidor pode construir o client (`new Anthropic(...)`) e injetá-lo — em
+ * teste, um fake sem rede. Sem client injetado, o driver constrói um sob demanda
+ * (peer OPCIONAL `@anthropic-ai/sdk`; `ANTHROPIC_API_KEY` do ambiente vale).
+ *
+ * `extract` usa tool forçado (`tool_choice: {type: 'tool'}` garante exatamente um
+ * bloco `tool_use`) com o JSON Schema derivado do schema zod, e VALIDA a resposta
+ * pelo próprio `Schema` do protocolo antes de devolver — o contrato da action é o
+ * contrato do modelo. Upgrade futuro: `output_config.format` (SDK ≥0.35, sampling
+ * restrito por gramática) quando valer alargar o subset injetável do client.
+ */
+
+import { zodToJsonSchema } from 'zod-to-json-schema'
+import type {
+  AiAdapter,
+  AiCompleteOptions,
+  AiMessage,
+  AiRunOptions,
+  AiRunResult,
+  AskQuestion,
+  ChatEvent,
+  Schema,
+} from '../../core/index.ts'
+import { ASK_INPUT_SCHEMA, ASK_TOOL_DESCRIPTION, ASK_USER_TOOL, formatAnswers } from '../ask.ts'
+
+/** Injeta a tool reservada `ask_user` no catálogo quando há `onAsk` (round-trip de perguntar
+ *  à pessoa) — assim o consumidor só precisa passar o handler; a tool aparece pro modelo. */
+function withAskTool(
+  tools: Array<{ name: string; description: string; input_schema: unknown }>,
+  opts: AiRunOptions,
+): Array<{ name: string; description: string; input_schema: unknown }> {
+  if (opts.onAsk === undefined || tools.some((t) => t.name === ASK_USER_TOOL)) return tools
+  return [...tools, { name: ASK_USER_TOOL, description: ASK_TOOL_DESCRIPTION, input_schema: ASK_INPUT_SCHEMA }]
+}
+
+/** Executa uma tool escolhida pelo modelo. A `ask_user` é INTERCEPTADA: com `onAsk`, faz o
+ *  round-trip real; sem ele, recusa com erro acionável (nunca dead-end silencioso). O resto
+ *  cai no `execute` do consumidor. */
+async function callTool(name: string, input: unknown, opts: AiRunOptions): Promise<unknown> {
+  if (name === ASK_USER_TOOL) {
+    const questions = ((input as { questions?: AskQuestion[] })?.questions ?? []) as AskQuestion[]
+    if (opts.onAsk !== undefined) {
+      const answers = await opts.onAsk(questions)
+      return { text: formatAnswers(questions, answers) }
+    }
+    return {
+      error:
+        'Não há canal interativo para perguntar à pessoa aqui. Faça a pergunta no seu texto de ' +
+        'resposta e siga com o melhor palpite — não trave nem invente que perguntou.',
+    }
+  }
+  return opts.execute(name, input)
+}
+
+/** O subset do client Anthropic que o driver usa (injetável em teste). O `stream` é
+ *  opcional: com ele, `runStream` emite texto token a token; sem ele (ex.: fake de
+ *  teste só com `create`), o texto de cada passo sai como um delta único. */
+export interface AnthropicClientLike {
+  messages: {
+    create(params: Record<string, unknown>): Promise<unknown>
+    stream?(params: Record<string, unknown>): AsyncIterable<unknown> & { finalMessage(): Promise<unknown> }
+  }
+}
+
+export interface AnthropicAiOptions {
+  /** Client pronto (injetável em teste). Default: `new Anthropic()` do peer, sob demanda. */
+  client?: AnthropicClientLike
+  /** API key pro client default. Sem ela, o SDK lê `ANTHROPIC_API_KEY` do ambiente. */
+  apiKey?: string
+  /** Modelo default das chamadas (por chamada via opts). Default: haiku (rápido/barato). */
+  model?: string
+  /** Teto default de tokens de saída (default 1024). */
+  maxTokens?: number
+  /** Nome do adapter (default 'anthropic'). */
+  name?: string
+  /**
+   * Conversor schema → JSON Schema do tool (injetável). Default: `zod-to-json-schema`
+   * inline (sem $ref) — cobre os schemas zod que as actions da casa usam.
+   */
+  toJsonSchema?: (schema: unknown) => unknown
+}
+
+export const DEFAULT_ANTHROPIC_MODEL = 'claude-haiku-4-5-20251001'
+
+// Import sob demanda do SDK (peer opcional): cacheado após o primeiro uso.
+let sdkPromise: Promise<typeof import('@anthropic-ai/sdk')> | null = null
+function sdk(): Promise<typeof import('@anthropic-ai/sdk')> {
+  sdkPromise ??= import('@anthropic-ai/sdk').catch(() => {
+    sdkPromise = null
+    throw new Error('ai/anthropic precisa do peer @anthropic-ai/sdk — `pnpm add @anthropic-ai/sdk`.')
+  })
+  return sdkPromise
+}
+
+function defaultToJsonSchema(schema: unknown): unknown {
+  return zodToJsonSchema(schema as Parameters<typeof zodToJsonSchema>[0], { $refStrategy: 'none' })
+}
+
+interface ContentBlock {
+  type: string
+  text?: string
+  input?: unknown
+  id?: string
+  name?: string
+}
+
+export function anthropicAi(options: AnthropicAiOptions = {}): AiAdapter {
+  const model = options.model ?? DEFAULT_ANTHROPIC_MODEL
+  const maxTokens = options.maxTokens ?? 1024
+  const toJsonSchema = options.toJsonSchema ?? defaultToJsonSchema
+
+  let clientPromise: Promise<AnthropicClientLike> | null = null
+  function client(): Promise<AnthropicClientLike> {
+    if (options.client !== undefined) return Promise.resolve(options.client)
+    // O create real é overloaded (streaming/non-streaming); o subset injetável cobre o driver.
+    clientPromise ??= sdk().then(
+      ({ default: Anthropic }) =>
+        new Anthropic(options.apiKey !== undefined ? { apiKey: options.apiKey } : {}) as never,
+    )
+    return clientPromise
+  }
+
+  function baseParams(opts?: AiCompleteOptions): Record<string, unknown> {
+    return {
+      model: opts?.model ?? model,
+      max_tokens: opts?.maxTokens ?? maxTokens,
+      ...(opts?.system !== undefined ? { system: opts.system } : {}),
+      ...(opts?.temperature !== undefined ? { temperature: opts.temperature } : {}),
+    }
+  }
+
+  return {
+    name: options.name ?? 'anthropic',
+    kind: 'ai',
+
+    async complete(prompt: string, opts?: AiCompleteOptions): Promise<string> {
+      const c = await client()
+      const response = (await c.messages.create({
+        ...baseParams(opts),
+        messages: [{ role: 'user', content: prompt }],
+      })) as { content: ContentBlock[] }
+      return response.content
+        .filter((b) => b.type === 'text')
+        .map((b) => b.text ?? '')
+        .join('')
+    },
+
+    async extract<T>(prompt: string, schema: Schema<T>, opts?: AiCompleteOptions): Promise<T> {
+      const inputSchema = toJsonSchema(schema)
+      // A API de tools exige objeto na raiz — schema de action já é (z.object).
+      if ((inputSchema as { type?: string }).type !== 'object') {
+        throw new Error('ai/anthropic extract: o schema precisa ser um objeto na raiz (ex.: z.object).')
+      }
+      const c = await client()
+      const response = (await c.messages.create({
+        ...baseParams(opts),
+        tools: [
+          {
+            name: 'extract',
+            description: 'Devolve o dado extraído, exatamente no formato pedido.',
+            input_schema: inputSchema,
+          },
+        ],
+        tool_choice: { type: 'tool', name: 'extract' },
+        messages: [{ role: 'user', content: prompt }],
+      })) as { content: ContentBlock[] }
+
+      const toolUse = response.content.find((b) => b.type === 'tool_use')
+      if (toolUse === undefined) {
+        throw new Error('ai/anthropic extract: resposta sem bloco tool_use (inesperado com tool forçado).')
+      }
+      const result = await Promise.resolve(schema['~standard'].validate(toolUse.input))
+      if ('issues' in result && result.issues !== undefined) {
+        const detail = result.issues.map((i) => `${(i.path ?? []).join('.')}: ${i.message}`).join('; ')
+        throw new Error(`ai/anthropic extract: resposta do modelo reprovou no schema — ${detail}`)
+      }
+      return (result as { value: T }).value
+    },
+
+    async run(input: string | AiMessage[], opts: AiRunOptions): Promise<AiRunResult> {
+      const c = await client()
+      const tools = withAskTool(
+        opts.tools.map((t) => ({
+          name: t.name,
+          description: t.description,
+          input_schema: toJsonSchema(t.inputSchema),
+        })),
+        opts,
+      )
+      // Mensagens no formato Anthropic — crescem com tool_use/tool_result a cada passo.
+      const messages: Array<{ role: string; content: unknown }> =
+        typeof input === 'string'
+          ? [{ role: 'user', content: input }]
+          : input.map((m) => ({ role: m.role, content: m.content }))
+
+      const maxSteps = opts.maxSteps ?? 8
+      const calls: Array<{ name: string; input: unknown }> = []
+
+      for (let steps = 1; steps <= maxSteps; steps++) {
+        const response = (await c.messages.create({
+          ...baseParams(opts),
+          tools,
+          messages,
+        })) as { content: ContentBlock[] }
+        messages.push({ role: 'assistant', content: response.content })
+
+        const toolUses = response.content.filter((b) => b.type === 'tool_use')
+        if (toolUses.length === 0) {
+          const text = response.content
+            .filter((b) => b.type === 'text')
+            .map((b) => b.text ?? '')
+            .join('')
+          return { text, steps, calls }
+        }
+
+        // Executa cada tool escolhida e devolve o resultado (ou o erro) pro modelo.
+        const results = []
+        for (const tu of toolUses) {
+          calls.push({ name: tu.name ?? '', input: tu.input })
+          let out: unknown
+          try {
+            out = await callTool(tu.name ?? '', tu.input, opts)
+          } catch (err) {
+            out = { error: err instanceof Error ? err.message : String(err) }
+          }
+          results.push({
+            type: 'tool_result',
+            tool_use_id: tu.id ?? '',
+            content: JSON.stringify(out ?? null),
+          })
+        }
+        messages.push({ role: 'user', content: results })
+      }
+
+      // Bateu o teto de passos sem uma resposta final em texto.
+      return { text: 'Não consegui concluir dentro do limite de passos.', steps: maxSteps, calls }
+    },
+
+    async *runStream(input: string | AiMessage[], opts: AiRunOptions): AsyncIterable<ChatEvent> {
+      const c = await client()
+      const tools = withAskTool(
+        opts.tools.map((t) => ({
+          name: t.name,
+          description: t.description,
+          input_schema: toJsonSchema(t.inputSchema),
+        })),
+        opts,
+      )
+      const messages: Array<{ role: string; content: unknown }> =
+        typeof input === 'string'
+          ? [{ role: 'user', content: input }]
+          : input.map((m) => ({ role: m.role, content: m.content }))
+
+      const maxSteps = opts.maxSteps ?? 8
+
+      for (let steps = 1; steps <= maxSteps; steps++) {
+        const params = { ...baseParams(opts), tools, messages }
+        let content: ContentBlock[]
+        if (typeof c.messages.stream === 'function') {
+          // Streaming de verdade: os deltas de texto saem conforme o modelo gera.
+          const stream = c.messages.stream(params)
+          for await (const event of stream) {
+            const e = event as { type?: string; delta?: { type?: string; text?: string } }
+            if (e.type === 'content_block_delta' && e.delta?.type === 'text_delta' && e.delta.text) {
+              yield { type: 'text', delta: e.delta.text }
+            }
+          }
+          content = ((await stream.finalMessage()) as { content: ContentBlock[] }).content
+        } else {
+          // Fallback sem stream (ex.: fake de teste): o texto do passo vira um delta único.
+          content = ((await c.messages.create(params)) as { content: ContentBlock[] }).content
+          const text = content
+            .filter((b) => b.type === 'text')
+            .map((b) => b.text ?? '')
+            .join('')
+          if (text !== '') yield { type: 'text', delta: text }
+        }
+        messages.push({ role: 'assistant', content })
+
+        const toolUses = content.filter((b) => b.type === 'tool_use')
+        if (toolUses.length === 0) {
+          yield { type: 'done', ok: true }
+          return
+        }
+
+        const results = []
+        for (const tu of toolUses) {
+          yield { type: 'tool', name: tu.name ?? '' }
+          let out: unknown
+          try {
+            out = await callTool(tu.name ?? '', tu.input, opts)
+          } catch (err) {
+            out = { error: err instanceof Error ? err.message : String(err) }
+          }
+          results.push({
+            type: 'tool_result',
+            tool_use_id: tu.id ?? '',
+            content: JSON.stringify(out ?? null),
+          })
+        }
+        messages.push({ role: 'user', content: results })
+      }
+
+      yield { type: 'done', ok: false, error: 'Não consegui concluir dentro do limite de passos.' }
+    },
+  }
+}

package/src/ai/index.ts

@@ -0,0 +1,17 @@
+/**
+ * @softize/opus/ai — a capability de IA generativa (EXPERIMENTAL).
+ *
+ * O contrato (`AiAdapter`) vive no core: `complete` (texto → texto) e `extract`
+ * (texto → objeto VALIDADO por um `Schema` do protocolo — o mesmo tipo de schema
+ * das actions vira o contrato da resposta do modelo). Driver em `ai/anthropic`.
+ * A superfície é a mínima de backoffice e cresce por reincidência — não por
+ * especulação (streaming, chat multi-turn e tools livres entram quando um caso
+ * real cobrar).
+ */
+
+export type { AiAdapter, AiCompleteOptions } from '../core/index.ts'
+// Elicitação — perguntar à pessoa no meio do turno (round-trip via `AiRunOptions.onAsk`).
+// O contrato (tipos) mora no core; aqui saem o nome reservado, o schema/descrição da tool e
+// o formatador. É o ponto de consistência pra qualquer consumidor (chat, copilot, MCP externo).
+export type { AskOption, AskQuestion, AskAnswer } from '../core/index.ts'
+export { ASK_USER_TOOL, ASK_TOOL_DESCRIPTION, ASK_INPUT_SCHEMA, formatAnswers } from './ask.ts'

package/src/audit/drivers/console.ts

@@ -0,0 +1,117 @@
+/**
+ * @softize/opus/audit/console — Console sink driver
+ *
+ * Imprime `AuditRecord` no stdout/stderr. Útil em dev pra inspeção
+ * imediata e em testes; em produção, prefira sinks persistentes (/pg,
+ * sentry, datadog).
+ *
+ * Formatos:
+ *   - 'pretty'  — multi-linha com cores ANSI (dev default)
+ *   - 'json'    — single-line JSON (prod default; parseável)
+ *
+ * Default: 'pretty' se TTY, 'json' caso contrário.
+ */
+
+import type { AuditRecord, AuditSink } from '../../core/index.ts'
+import { redactRecord } from '../index.ts'
+
+export interface ConsoleAuditOptions {
+  /**
+   * Formato de output. Default: 'pretty' se process.stdout.isTTY, senão 'json'.
+   */
+  format?: 'pretty' | 'json'
+
+  /**
+   * Override do logger usado pra escrever. Default: console.log / console.error.
+   * Útil pra capturar em testes ou redirecionar.
+   */
+  write?: (level: 'info' | 'error', line: string) => void
+
+  /**
+   * Nome do sink (default 'console'). Útil quando registrando múltiplos
+   * sinks console pra contextos diferentes.
+   */
+  name?: string
+
+  /**
+   * Redator aplicado a input/output antes de imprimir (ex.: `redactDeep` de
+   * `@softize/opus/audit`) — terminal/log agregado também vaza senha.
+   */
+  redact?: (value: unknown) => unknown
+}
+
+export function consoleAudit(options: ConsoleAuditOptions = {}): AuditSink {
+  const {
+    format = defaultFormat(),
+    write = defaultWrite,
+    name = 'console',
+    redact,
+  } = options
+
+  return {
+    name,
+    kind: 'audit',
+    emit(record: AuditRecord) {
+      const r = redact === undefined ? record : redactRecord(record, redact)
+      const line = format === 'pretty' ? renderPretty(r) : renderJson(r)
+      const level = r.outcome === 'error' ? 'error' : 'info'
+      write(level, line)
+    },
+    healthCheck() {
+      return Promise.resolve({ ok: true })
+    },
+  }
+}
+
+// =============================================================================
+// Format helpers
+// =============================================================================
+
+function defaultFormat(): 'pretty' | 'json' {
+  /* v8 ignore next — ambiente Node sem stdout.isTTY (raro) */
+  if (typeof process === 'undefined' || process.stdout === undefined) return 'json'
+  return process.stdout.isTTY === true ? 'pretty' : 'json'
+}
+
+function defaultWrite(level: 'info' | 'error', line: string): void {
+  const target = level === 'error' ? console.error : console.log
+  target(line)
+}
+
+function renderJson(record: AuditRecord): string {
+  return JSON.stringify(record)
+}
+
+function renderPretty(record: AuditRecord): string {
+  const tag = record.outcome === 'success' ? ANSI.green('✓') : ANSI.red('✗')
+  const sev = paintSeverity(record.severity)
+  const head = `${tag} ${ANSI.bold(record.action)} ${ANSI.dim(record.id)}`
+  const meta = [
+    `${ANSI.dim('outcome:')} ${record.outcome}`,
+    `${ANSI.dim('severity:')} ${sev}`,
+    `${ANSI.dim('duration:')} ${record.durationMs.toFixed(2)}ms`,
+    `${ANSI.dim('actor:')} ${record.actor.id ?? 'system'}`,
+    ...(record.tenant !== null && record.tenant !== undefined
+      ? [`${ANSI.dim('tenant:')} ${record.tenant}`]
+      : []),
+  ].join('  ')
+  return `${head}\n  ${meta}`
+}
+
+function paintSeverity(s: AuditRecord['severity']): string {
+  if (s === 'error') return ANSI.red(s)
+  if (s === 'warning') return ANSI.yellow(s)
+  return ANSI.green(s)
+}
+
+// =============================================================================
+// ANSI helpers (zero-dep)
+// =============================================================================
+
+const ANSI = {
+  bold: (s: string) => `\x1b[1m${s}\x1b[0m`,
+  dim: (s: string) => `\x1b[2m${s}\x1b[0m`,
+  red: (s: string) => `\x1b[31m${s}\x1b[0m`,
+  green: (s: string) => `\x1b[32m${s}\x1b[0m`,
+  yellow: (s: string) => `\x1b[33m${s}\x1b[0m`,
+}

package/src/audit/drivers/pg.ts

@@ -0,0 +1,172 @@
+/**
+ * @softize/opus/audit/pg — PostgreSQL sink driver
+ *
+ * Persiste `AuditRecord` numa tabela Postgres via `pg.Pool`. Schema esperado:
+ *
+ *   CREATE TABLE audit_log (
+ *     id              uuid PRIMARY KEY,
+ *     timestamp       timestamptz NOT NULL,
+ *     action          text NOT NULL,
+ *     outcome         text NOT NULL,
+ *     duration_ms     numeric NOT NULL,
+ *     provenance_kind text NOT NULL,   -- discriminator (http, schedule, reaction, ...)
+ *     provenance      jsonb NOT NULL,  -- objeto completo da Provenance (incl. chain)
+ *     actor_id        text,
+ *     actor_type      text,
+ *     tenant          text,
+ *     input           jsonb,
+ *     output          jsonb,
+ *     error           jsonb,
+ *     severity        text NOT NULL,
+ *     trace_request_id        text,
+ *     trace_parent_action_id  text,
+ *     meta            jsonb
+ *   );
+ *   CREATE INDEX audit_provenance_kind_idx ON audit_log(provenance_kind);
+ *
+ * Tabela é criada pelo consumer (migration). Adapter apenas insere.
+ *
+ * Uso:
+ *   import { Pool } from 'pg'
+ *   import { pgAudit } from '@softize/opus/audit/pg'
+ *
+ *   const pool = new Pool({ connectionString: process.env.DATABASE_URL })
+ *   createRuntime({ audit: pgAudit({ pool, table: 'audit_log' }) })
+ *
+ * Com dado sensível, plugue o redator global (recursivo, por nome de chave):
+ *
+ *   import { redactDeep } from '@softize/opus/audit'
+ *   pgAudit({ pool, redact: redactDeep })
+ */
+
+import type { AuditRecord, AuditSink, HealthStatus } from '../../core/index.ts'
+import { redactRecord } from '../index.ts'
+
+/**
+ * Subset mínimo de `pg.Pool` que precisamos. Aceitar qualquer objeto com
+ * `query()` evita dep direta de `pg` no tipo público; aceita pools-like
+ * (e.g., wrappers de Neon, Supabase pooler).
+ */
+export interface PgQueryable {
+  query(text: string, values?: unknown[]): Promise<unknown>
+}
+
+export interface PgAuditOptions {
+  /** Pool ou conexão pg-compatível. */
+  pool: PgQueryable
+
+  /** Nome da tabela. Default 'audit_log'. */
+  table?: string
+
+  /** Nome do sink (default 'pg'). */
+  name?: string
+
+  /**
+   * Redator aplicado a input/output ANTES de persistir — sem ele, os dois vão
+   * CRUS (user.create/setPassword gravaria senha em claro no log). Pra dado
+   * sensível, plugue o `redactDeep` de `@softize/opus/audit` (recursivo, por
+   * nome de chave) ou um redator próprio. O `AuditConfig.redact` por action
+   * (dot-paths) continua valendo — este é o cinto de segurança global do sink.
+   */
+  redact?: (value: unknown) => unknown
+}
+
+export function pgAudit(options: PgAuditOptions): AuditSink {
+  const { pool, table = 'audit_log', name = 'pg', redact } = options
+  validateTableName(table)
+  const sql = buildInsertSql(table)
+
+  return {
+    name,
+    kind: 'audit',
+
+    async emit(record: AuditRecord) {
+      const values = recordToValues(redact === undefined ? record : redactRecord(record, redact))
+      await pool.query(sql, values)
+    },
+
+    async healthCheck(): Promise<HealthStatus> {
+      try {
+        await pool.query('SELECT 1')
+        return { ok: true }
+      } catch (err) {
+        return { ok: false, details: { error: String(err) } }
+      }
+    },
+  }
+}
+
+// =============================================================================
+// SQL builder
+// =============================================================================
+
+const COLUMNS = [
+  'id',
+  'timestamp',
+  'action',
+  'outcome',
+  'duration_ms',
+  'provenance_kind',
+  'provenance',
+  'actor_id',
+  'actor_type',
+  'tenant',
+  'input',
+  'output',
+  'error',
+  'severity',
+  'trace_request_id',
+  'trace_parent_action_id',
+  'meta',
+] as const
+
+function buildInsertSql(table: string): string {
+  const cols = COLUMNS.join(', ')
+  const params = COLUMNS.map((_, i) => `$${i + 1}`).join(', ')
+  return `INSERT INTO ${table} (${cols}) VALUES (${params})`
+}
+
+function recordToValues(r: AuditRecord): unknown[] {
+  return [
+    r.id,
+    r.timestamp,
+    r.action,
+    r.outcome,
+    r.durationMs,
+    r.provenance.kind,
+    jsonOrNull(r.provenance),
+    r.actor.id,
+    r.actor.type ?? null,
+    r.tenant ?? null,
+    jsonOrNull(r.input),
+    jsonOrNull(r.output),
+    jsonOrNull(r.error),
+    r.severity,
+    r.trace?.requestId ?? null,
+    r.trace?.parentActionId ?? null,
+    jsonOrNull(r.meta),
+  ]
+}
+
+function jsonOrNull(value: unknown): string | null {
+  if (value === undefined || value === null) return null
+  return JSON.stringify(value)
+}
+
+// =============================================================================
+// Safety
+// =============================================================================
+
+/**
+ * Valida que `table` é um identificador SQL seguro. Aceita
+ * `schema.table` opcional. Lança se conter caracteres suspeitos —
+ * preveni injection já que table name não pode ser parametrizado.
+ */
+function validateTableName(table: string): void {
+  if (!/^[a-z_][a-z0-9_]*(\.[a-z_][a-z0-9_]*)?$/i.test(table)) {
+    throw new Error(
+      `pgAudit: invalid table name "${table}". ` +
+        `Must match /^[a-z_][a-z0-9_]*(\\.[a-z_][a-z0-9_]*)?$/i.`,
+    )
+  }
+}