@softize/opus 9.0.8 → 9.1.0

package/src/observability/drivers/opentelemetry.ts

@@ -0,0 +1,165 @@
+/**
+ * @softize/opus/observability/opentelemetry
+ *
+ * Driver fino sobre `@opentelemetry/api`: não cria provider, exporter, collector nem
+ * context manager. O app configura seu SDK OTel e pode injetar um Tracer nos testes.
+ */
+
+import {
+  context,
+  createTraceState,
+  SpanKind,
+  SpanStatusCode,
+  trace,
+  TraceFlags,
+  type Attributes,
+  type Span,
+  type SpanContext,
+  type Tracer,
+} from '@opentelemetry/api'
+import type {
+  ActionResult,
+  HealthStatus,
+  ObservabilityAdapter,
+  ObservabilityOperation,
+  TraceContext,
+} from '../../core/index.ts'
+
+export interface OpenTelemetryObservabilityOptions {
+  /** Tracer injetado; default usa o provider global configurado pelo app. */
+  tracer?: Tracer
+  /** Nome do instrumentation scope. */
+  instrumentationName?: string
+  /** Versão do instrumentation scope. */
+  instrumentationVersion?: string
+  /** Nome do adapter no health agregado. */
+  name?: string
+  /** Shutdown opt-in de recurso possuído pelo caller; nunca desliga provider global sozinho. */
+  shutdown?: () => Promise<void> | void
+  /** Health adicional do wiring/exporter possuído pelo caller. */
+  healthCheck?: () => Promise<HealthStatus> | HealthStatus
+}
+
+export function openTelemetryObservability(
+  options: OpenTelemetryObservabilityOptions = {},
+): ObservabilityAdapter {
+  const {
+    name = 'opentelemetry',
+    instrumentationName = '@softize/opus',
+    instrumentationVersion,
+  } = options
+  const tracer = options.tracer ?? trace.getTracer(instrumentationName, instrumentationVersion)
+
+  return {
+    name,
+    kind: 'observability',
+
+    async runInSpan<T>(
+      operation: ObservabilityOperation,
+      run: (traceContext: TraceContext) => Promise<T>,
+    ): Promise<T> {
+      const parent = parentContext(operation.parent)
+      return tracer.startActiveSpan(
+        spanName(operation),
+        {
+          kind: SpanKind.INTERNAL,
+          attributes: operationAttributes(operation),
+        },
+        parent,
+        async (span) => runOperation(operation, span, run),
+      )
+    },
+
+    async healthCheck(): Promise<HealthStatus> {
+      if (options.healthCheck !== undefined) return options.healthCheck()
+      return { ok: true, details: { api: 'configured' } }
+    },
+
+    async dispose(): Promise<void> {
+      await options.shutdown?.()
+    },
+  }
+}
+
+async function runOperation<T>(
+  operation: ObservabilityOperation,
+  span: Span,
+  run: (traceContext: TraceContext) => Promise<T>,
+): Promise<T> {
+  const spanContext = span.spanContext()
+  if (!trace.isSpanContextValid(spanContext)) {
+    span.end()
+    throw new Error(
+      'OpenTelemetry tracer is not recording valid spans; configure a TracerProvider before the Opus runtime',
+    )
+  }
+  try {
+    const result = await run(fromSpanContext(spanContext))
+    const failed = operation.resultKind === 'action-result' && isFailedActionResult(result)
+    span.setAttribute('opus.outcome', failed ? 'error' : 'success')
+    if (failed) {
+      span.setAttribute('opus.error.category', result.error.category)
+      span.setStatus({ code: SpanStatusCode.ERROR })
+    } else {
+      span.setStatus({ code: SpanStatusCode.OK })
+    }
+    return result
+  } catch (err) {
+    span.setAttribute('opus.outcome', 'error')
+    span.setStatus({ code: SpanStatusCode.ERROR })
+    throw err
+  } finally {
+    span.end()
+  }
+}
+
+function parentContext(parent: TraceContext | undefined) {
+  if (parent === undefined) return context.active()
+  const spanContext = toSpanContext(parent)
+  return trace.isSpanContextValid(spanContext)
+    ? trace.setSpanContext(context.active(), spanContext)
+    : context.active()
+}
+
+function toSpanContext(value: TraceContext): SpanContext {
+  return {
+    traceId: value.traceId,
+    spanId: value.spanId ?? '0000000000000000',
+    traceFlags: value.traceFlags ?? TraceFlags.NONE,
+    ...(value.traceState !== undefined ? { traceState: createTraceState(value.traceState) } : {}),
+    isRemote: true,
+  }
+}
+
+function fromSpanContext(value: SpanContext): TraceContext {
+  const traceState = value.traceState?.serialize()
+  return {
+    traceId: value.traceId,
+    spanId: value.spanId,
+    traceFlags: value.traceFlags,
+    ...(traceState !== undefined && traceState.length > 0 ? { traceState } : {}),
+  }
+}
+
+function spanName(operation: ObservabilityOperation): string {
+  return `opus.${operation.kind} ${operation.name}`
+}
+
+/** Allowlist de baixa cardinalidade; IDs de execução/atores nunca viram atributos. */
+function operationAttributes(operation: ObservabilityOperation): Attributes {
+  const attributes: Attributes = {
+    'opus.operation.kind': operation.kind,
+    'opus.result.kind': operation.resultKind,
+  }
+  const actionKind = operation.attributes?.['opus.action.kind']
+  if (typeof actionKind === 'string') attributes['opus.action.kind'] = actionKind
+  const eventType = operation.attributes?.['opus.event.type']
+  if (typeof eventType === 'string') attributes['opus.event.type'] = eventType
+  return attributes
+}
+
+function isFailedActionResult(value: unknown): value is Extract<ActionResult<unknown>, { ok: false }> {
+  return typeof value === 'object' && value !== null && 'ok' in value && value.ok === false &&
+    'error' in value && typeof value.error === 'object' && value.error !== null &&
+    'category' in value.error && typeof value.error.category === 'string'
+}

package/src/observability/index.ts

@@ -0,0 +1,8 @@
+/**
+ * @softize/opus/observability — superfície dos drivers de observabilidade.
+ *
+ * A porta vendor-neutral (`ObservabilityAdapter`, `TraceContext`) permanece no core.
+ * Drivers concretos vivem em subpaths, como `./opentelemetry`.
+ */
+
+export {}

package/src/queue/drivers/bullmq.ts

@@ -6,8 +6,8 @@
  *
  * Worker (consumer-side) é responsabilidade do consumer — esse adapter
  * só **enfileira** e **consulta**. Pra processar, o consumer registra
- * um `new Worker(queueName, processor, { connection })` que chama
- * `runtime.execute()` no callback.
+ * um `new Worker(queueName, processor, { connection })`, reidrata auth e chama
+ * `runtime.executeJob()` no callback.
  *
  * Uso:
  *   import { Queue } from 'bullmq'
@@ -23,6 +23,7 @@ import type {
   JobStatus,
   QueueAdapter,
 } from '../../core/index.ts'
+import { normalizeTraceContext } from '../../core/index.ts'
 
 // =============================================================================
 // BullMQ-compatible interfaces (zero direct dep no tipo público)
@@ -58,11 +59,18 @@ export interface BullMQQueue {
   add(
     name: string,
     data: unknown,
-    opts?: { jobId?: string },
+    opts?: BullMQAddOptions,
   ): Promise<BullMQJob>
   getJob(jobId: string): Promise<BullMQJob | undefined | null>
 }
 
+export interface BullMQAddOptions {
+  jobId?: string
+  attempts?: number
+  priority?: number
+  backoff?: { type: 'fixed' | 'exponential'; delay: number }
+}
+
 // =============================================================================
 // Adapter factory
 // =============================================================================
@@ -80,8 +88,8 @@ export function bullmqQueue(options: BullmqQueueOptions): QueueAdapter {
     kind: 'queue',
 
     async enqueue(spec: JobSpec): Promise<JobHandle> {
-      const job = await queue.add(spec.action, spec, { jobId: spec.jobId })
-      return jobToHandle(spec.action, job, 'queued')
+      const job = await queue.add(spec.action, spec, bullmqOptions(spec))
+      return jobToHandle(spec.action, job, 'queued', normalizeTraceContext(spec.ctx.trace))
     },
 
     async status(jobId: string): Promise<JobHandle | null> {
@@ -101,6 +109,31 @@ export function bullmqQueue(options: BullmqQueueOptions): QueueAdapter {
   }
 }
 
+function bullmqOptions(spec: JobSpec): BullMQAddOptions {
+  const options: BullMQAddOptions = { jobId: spec.jobId }
+  if (spec.config.priority !== undefined) {
+    options.priority = { high: 1, normal: 5, low: 10 }[spec.config.priority]
+  }
+  const retry = spec.config.retry
+  if (retry !== undefined) {
+    options.attempts = retry.attempts
+    if (retry.backoff?.kind === 'fixed') {
+      options.backoff = { type: 'fixed', delay: retry.backoff.delayMs }
+    } else if (retry.backoff?.kind === 'exponential') {
+      if (
+        (retry.backoff.multiplier !== undefined && retry.backoff.multiplier !== 2) ||
+        retry.backoff.maxMs !== undefined
+      ) {
+        throw new Error(
+          'BullMQ native exponential backoff supports multiplier 2 without maxMs; configure a worker backoffStrategy for custom behavior',
+        )
+      }
+      options.backoff = { type: 'exponential', delay: retry.backoff.initialMs }
+    }
+  }
+  return options
+}
+
 // =============================================================================
 // Mapping
 // =============================================================================
@@ -136,6 +169,7 @@ function jobToHandle(
   action: string,
   job: BullMQJob,
   status: JobStatus,
+  trace = readTrace(job),
 ): JobHandle {
   const handle: JobHandle = {
     jobId: job.id ?? '',
@@ -144,6 +178,7 @@ function jobToHandle(
     enqueuedAt: toIso(job.timestamp),
     attempts: job.attemptsMade,
   }
+  if (trace !== undefined) handle.trace = trace
   if (job.processedOn !== undefined) handle.startedAt = toIso(job.processedOn)
   if (job.finishedOn !== undefined) handle.finishedAt = toIso(job.finishedOn)
   if (status === 'done' && job.returnvalue !== undefined) handle.data = job.returnvalue
@@ -161,6 +196,13 @@ function jobToHandle(
   return handle
 }
 
+function readTrace(job: BullMQJob): JobHandle['trace'] | undefined {
+  if (typeof job.data !== 'object' || job.data === null || !('ctx' in job.data)) return undefined
+  const ctx = (job.data as { ctx?: unknown }).ctx
+  if (typeof ctx !== 'object' || ctx === null || !('trace' in ctx)) return undefined
+  return normalizeTraceContext((ctx as { trace?: unknown }).trace)
+}
+
 function readAction(job: BullMQJob): string {
   if (
     typeof job.data === 'object' &&

package/src/server/drivers/fastify.ts

@@ -35,12 +35,14 @@ import {
 } from '../../schema/openapi.ts'
 import {
   httpStatusFor,
+  extractW3CTraceContext,
   inputSourceFor,
   methodFor,
   pathFor,
   serializeResult,
   shouldMountPublicly,
   successStatusFor,
+  w3cTraceResponseHeaders,
 } from '../index.ts'
 
 // =============================================================================
@@ -62,6 +64,9 @@ export interface FastifyServerOptions {
 
   /** Servers do OpenAPI document. */
   openapiServers?: OpenAPIServer[]
+
+  /** Propagação HTTP opt-in. `'w3c'` extrai/injeta traceparent + tracestate. */
+  traceContext?: false | 'w3c'
 }
 
 // =============================================================================
@@ -74,6 +79,7 @@ export function fastifyServer(options: FastifyServerOptions): ServerAdapter {
     apiPrefix = '/api',
     openapiInfo = { title: 'tbdlib API', version: '0.0.0' },
     openapiServers,
+    traceContext = false,
   } = options
   let runtime: RuntimeRef | undefined
   const mountedActions: ActionDef[] = []
@@ -104,7 +110,7 @@ export function fastifyServer(options: FastifyServerOptions): ServerAdapter {
 
       const handler = async (req: FastifyRequest, reply: FastifyReply) => {
         const rt = requireRuntime()
-        const ctx = await resolveCtx(rt, req)
+        const ctx = await resolveCtx(rt, req, traceContext)
         const input = source === 'body' ? req.body : req.query
 
         const result = await rt.execute(action.name, input, ctx)
@@ -112,6 +118,11 @@ export function fastifyServer(options: FastifyServerOptions): ServerAdapter {
           ? successStatusFor(action)
           : httpStatusFor(result.error)
 
+        if (traceContext === 'w3c') {
+          for (const [key, value] of Object.entries(w3cTraceResponseHeaders(result.meta.trace))) {
+            reply.header(key, value)
+          }
+        }
         reply.code(status).send(serializeResult(result))
       }
 
@@ -138,11 +149,15 @@ export function fastifyServer(options: FastifyServerOptions): ServerAdapter {
 async function resolveCtx(
   rt: RuntimeRef,
   req: FastifyRequest,
+  traceContext: false | 'w3c',
 ): Promise<ContextBase> {
   const base = await resolveAuthBase(rt, req)
   // Fastify sempre popula req.id (auto-gen ou via genReqId opt). Não é optional.
   return {
     ...base,
+    ...(traceContext === 'w3c'
+      ? { trace: extractW3CTraceContext(req.headers as Record<string, string | string[] | undefined>) }
+      : {}),
     requestId: req.id,
     provenance: {
       kind: 'http',

package/src/server/drivers/node.ts

@@ -42,12 +42,14 @@ import {
 } from '../../schema/openapi.ts'
 import {
   httpStatusFor,
+  extractW3CTraceContext,
   inputSourceFor,
   methodFor,
   pathFor,
   serializeResult,
   shouldMountPublicly,
   successStatusFor,
+  w3cTraceResponseHeaders,
 } from '../index.ts'
 
 // =============================================================================
@@ -72,6 +74,9 @@ export interface NodeServerOptions {
 
   /** Servers do OpenAPI document. */
   openapiServers?: OpenAPIServer[]
+
+  /** Propagação HTTP opt-in. `'w3c'` extrai/injeta traceparent + tracestate. */
+  traceContext?: false | 'w3c'
 }
 
 export interface NodeServerHandle {
@@ -98,6 +103,7 @@ export function nodeServer(options: NodeServerOptions = {}): NodeServerHandle {
     endpoints,
     openapiInfo = { title: 'tbdlib API', version: '0.0.0' },
     openapiServers,
+    traceContext = false,
   } = options
 
   let runtime: RuntimeRef | undefined
@@ -142,7 +148,7 @@ export function nodeServer(options: NodeServerOptions = {}): NodeServerHandle {
       routes.set(`${method} ${path}`, async (req, res, url) => {
         const rt = requireRuntime()
         const requestId = crypto.randomUUID()
-        const ctx = await resolveCtx(rt, req, requestId)
+        const ctx = await resolveCtx(rt, req, requestId, traceContext)
 
         let input: unknown
         if (source === 'body') {
@@ -177,7 +183,7 @@ export function nodeServer(options: NodeServerOptions = {}): NodeServerHandle {
           ? successStatusFor(action)
           : httpStatusFor(result.error)
 
-        sendResult(res, status, result)
+        sendResult(res, status, result, traceContext === 'w3c')
       })
     },
 
@@ -235,10 +241,14 @@ async function resolveCtx(
   rt: RuntimeRef,
   req: IncomingMessage,
   requestId: string,
+  traceContext: false | 'w3c',
 ): Promise<ContextBase> {
   const base = await resolveAuthBase(rt, req)
   return {
     ...base,
+    ...(traceContext === 'w3c'
+      ? { trace: extractW3CTraceContext(req.headers) }
+      : {}),
     requestId,
     provenance: {
       kind: 'http',
@@ -275,9 +285,19 @@ async function readBody(req: IncomingMessage): Promise<string> {
   return body
 }
 
-function sendResult(res: ServerResponse, status: number, result: ActionResult<unknown>): void {
+function sendResult(
+  res: ServerResponse,
+  status: number,
+  result: ActionResult<unknown>,
+  injectTrace = false,
+): void {
   res.statusCode = status
   res.setHeader('content-type', 'application/json; charset=utf-8')
+  if (injectTrace) {
+    for (const [key, value] of Object.entries(w3cTraceResponseHeaders(result.meta.trace))) {
+      res.setHeader(key, value)
+    }
+  }
   res.end(JSON.stringify(serializeResult(result)))
 }
 

package/src/server/index.ts

@@ -15,8 +15,65 @@ import type {
   ActionError,
   ActionResult,
   ErrorCategory,
+  TraceContext,
 } from '../core/index.ts'
 
+// =============================================================================
+// W3C trace context
+// =============================================================================
+
+export type HttpHeaderValue = string | string[] | undefined
+
+/** Extrai somente traceparent v00 válido; tracestate é opcional e limitado a 512 bytes. */
+export function extractW3CTraceContext(
+  headers: Record<string, HttpHeaderValue>,
+): TraceContext | undefined {
+  const raw = firstHeader(headers['traceparent'])
+  if (raw === undefined) return undefined
+  const match = /^00-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/i.exec(raw.trim())
+  if (match === null) return undefined
+  const traceId = match[1]?.toLowerCase()
+  const spanId = match[2]?.toLowerCase()
+  const flags = match[3]
+  if (traceId === undefined || spanId === undefined || flags === undefined) return undefined
+  if (/^0+$/.test(traceId) || /^0+$/.test(spanId)) return undefined
+  const traceState = validTraceState(firstHeader(headers['tracestate']))
+  return {
+    traceId,
+    spanId,
+    traceFlags: Number.parseInt(flags, 16),
+    ...(traceState !== undefined ? { traceState } : {}),
+  }
+}
+
+export function w3cTraceResponseHeaders(
+  traceContext: TraceContext | undefined,
+): Record<string, string> {
+  if (traceContext === undefined || !validTraceIds(traceContext)) return {}
+  const flags = (traceContext.traceFlags ?? 0) & 0xff
+  return {
+    traceparent: `00-${traceContext.traceId}-${traceContext.spanId}-${flags.toString(16).padStart(2, '0')}`,
+    ...(validTraceState(traceContext.traceState) !== undefined
+      ? { tracestate: traceContext.traceState as string }
+      : {}),
+  }
+}
+
+function firstHeader(value: HttpHeaderValue): string | undefined {
+  return Array.isArray(value) ? (value.length === 1 ? value[0] : undefined) : value
+}
+
+function validTraceState(value: string | undefined): string | undefined {
+  if (value === undefined || value.length === 0 || value.length > 512) return undefined
+  return /[^\x20-\x7e]/.test(value) ? undefined : value
+}
+
+function validTraceIds(value: TraceContext): value is TraceContext & { spanId: string } {
+  return /^[0-9a-f]{32}$/i.test(value.traceId) && !/^0+$/.test(value.traceId) &&
+    typeof value.spanId === 'string' && /^[0-9a-f]{16}$/i.test(value.spanId) &&
+    !/^0+$/.test(value.spanId)
+}
+
 // =============================================================================
 // HTTP status mapping
 // =============================================================================

package/src/testing/index.ts

@@ -46,6 +46,7 @@ import type {
   StorageObject,
   StoragePutOptions,
   User,
+  TraceContext,
 } from '../core/index.ts'
 
 // =============================================================================
@@ -73,6 +74,7 @@ export interface TestContextOptions {
   storage?: StorageAdapter | null
   ai?: AiAdapter | null
   meta?: Record<string, unknown>
+  trace?: TraceContext
 }
 
 export interface TestContext {
@@ -133,6 +135,7 @@ export function testContext(options: TestContextOptions = {}): TestContext {
     storage: options.storage ?? null,
     ai: options.ai ? toBoundAi(options.ai) : null,
     provenance: { kind: 'system', source: 'test' },
+    ...(options.trace !== undefined ? { trace: options.trace } : {}),
     meta: options.meta ?? {},
   }
   return { ctx, emitted, logged }

package/src/ui/components/primitives/chat.tsx

@@ -212,7 +212,8 @@ const ChatTranscript = React.memo(function ChatTranscript({
 })
 
 /**
- * Chat da casa: lista de mensagens + composer (Enter envia / Shift+Enter quebra linha),
+ * Chat da casa: lista de mensagens + composer (Enter envia / Shift+Enter quebra linha;
+ * com o campo vazio, ↑/↓ navegam pelas mensagens anteriores do usuário),
  * transcript em turnos, fala do usuário em fundo discreto, assistente em Markdown direto
  * no corpo, tool como indicador vivo
  * (nunca mensagem) e artefatos via `renderArtifact`. Dois modos:
@@ -246,11 +247,52 @@ export function Chat({
   const [input, setInput] = React.useState('')
   const [ownBusy, setOwnBusy] = React.useState(false)
   const [ownActivity, setOwnActivity] = React.useState<string | null>(null)
+  const historyCursor = React.useRef<number | null>(null)
+  const historyDraft = React.useRef('')
 
   const items = controlled ? messages : ownItems
   const busy = controlled ? (busyProp ?? false) : ownBusy
   // Indicador: no controlado o app manda (undefined esconde); no autogerenciado segue o busy.
   const indicator = controlled ? activityProp : ownBusy ? ownActivity : undefined
+  const inputHistory = React.useMemo(
+    () => items.filter((item): item is ChatMessage => item.role === 'user').map((item) => item.content),
+    [items],
+  )
+
+  function changeInput(value: string): void {
+    historyCursor.current = null
+    setInput(value)
+  }
+
+  function showPreviousInput(): boolean {
+    if (inputHistory.length === 0) return false
+
+    if (historyCursor.current === null) {
+      // Não rouba ↑ do cursor em mensagens novas ou multilinha. A navegação começa no
+      // composer vazio, como em shells; depois disso ↑/↓ pertencem ao histórico.
+      if (input !== '') return false
+      historyDraft.current = input
+      historyCursor.current = inputHistory.length - 1
+    } else if (historyCursor.current > 0) {
+      historyCursor.current -= 1
+    }
+
+    setInput(inputHistory[historyCursor.current])
+    return true
+  }
+
+  function showNextInput(): boolean {
+    if (historyCursor.current === null) return false
+
+    if (historyCursor.current < inputHistory.length - 1) {
+      historyCursor.current += 1
+      setInput(inputHistory[historyCursor.current])
+    } else {
+      historyCursor.current = null
+      setInput(historyDraft.current)
+    }
+    return true
+  }
 
   const kickoffRan = React.useRef(false)
   React.useEffect(() => {
@@ -264,6 +306,8 @@ export function Chat({
   async function submit(): Promise<void> {
     const text = input.trim()
     if (text === '' || busy) return
+    historyCursor.current = null
+    historyDraft.current = ''
     setInput('')
 
     if (controlled) {
@@ -339,8 +383,10 @@ export function Chat({
         {notice}
         <Composer
           value={input}
-          onChange={setInput}
+          onChange={changeInput}
           onSubmit={() => void submit()}
+          onHistoryPrevious={showPreviousInput}
+          onHistoryNext={showNextInput}
           busy={busy}
           placeholder={placeholder}
           actions={composerActions}

package/src/ui/components/primitives/composer.tsx

@@ -12,6 +12,10 @@ export interface ComposerProps {
   onChange: (value: string) => void
   /** Enter (sem Shift) ou o botão enviar. Só dispara quando dá pra enviar (ver `submitDisabled`). */
   onSubmit: () => void
+  /** Navegação opcional pelo histórico do dono do composer. Retorne `true` quando a tecla
+   *  foi consumida; o `<Chat>` usa isso para ↑/↓ sem interferir no cursor normal. */
+  onHistoryPrevious?: () => boolean
+  onHistoryNext?: () => boolean
   /** Trava o composer enquanto o turno/ação corre — o enviar vira spinner. */
   busy?: boolean
   /** Gate EXTRA de envio além de "vazio" e "busy" (ex.: falta escolher o app). Desabilita o
@@ -39,6 +43,8 @@ export function Composer({
   value,
   onChange,
   onSubmit,
+  onHistoryPrevious,
+  onHistoryNext,
   busy = false,
   submitDisabled = false,
   placeholder = 'Escreva uma mensagem…',
@@ -59,6 +65,14 @@ export function Composer({
       value={value}
       onChange={(e) => onChange(e.target.value)}
       onKeyDown={(e) => {
+        if (e.key === 'ArrowUp' && onHistoryPrevious?.()) {
+          e.preventDefault()
+          return
+        }
+        if (e.key === 'ArrowDown' && onHistoryNext?.()) {
+          e.preventDefault()
+          return
+        }
         if (e.key === 'Enter' && !e.shiftKey) {
           e.preventDefault()
           fire()

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

@@ -31,6 +31,8 @@ interface AuditRecord {
   output?: unknown
   error?: ActionError
   severity: 'info' | 'warning' | 'error'
+  trace?: { requestId?: string; parentActionId?: string } // legado
+  traceContext?: TraceContext                              // vendor-neutral
   meta?: Record<string, unknown>
 }
 ```
@@ -48,6 +50,21 @@ const dev = consoleAudit()
 const prod = pgAudit({ pool, table: 'audit_log' })
 ```
 
+O default continua compatível com a tabela legada. Para persistir o contexto novo, primeiro
+adicione colunas próprias e depois habilite o opt-in — não reutilize as colunas legadas:
+
+```sql
+ALTER TABLE audit_log ADD COLUMN trace_id text;
+ALTER TABLE audit_log ADD COLUMN span_id text;
+```
+
+```ts
+const prod = pgAudit({ pool, traceContextColumns: true })
+```
+
+Rollouts com nomes existentes podem usar
+`traceContextColumns: { traceId: 'otel_trace_id', spanId: 'otel_span_id' }`.
+
 ## Dado sensível: o redator global
 
 Sem redator, os sinks persistem input e output **crus** — `user.create`/`setPassword`

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

@@ -1,6 +1,6 @@
 ## Básico
 
-Um chat mínimo: lista de mensagens + composer. A conversa é gerenciada por dentro (estado, loading, auto-scroll; **Enter** envia, **Shift+Enter** quebra linha) — a inteligência vem da prop `send`. O `greeting` é o estado vazio (centrado; some quando a conversa começa e NÃO entra no transcript). Dê altura ao container.
+Um chat mínimo: lista de mensagens + composer. A conversa é gerenciada por dentro (estado, loading, auto-scroll; **Enter** envia, **Shift+Enter** quebra linha) — a inteligência vem da prop `send`. Com o composer vazio, **↑** recupera as mensagens anteriores do usuário e **↓** volta em direção ao rascunho; durante a edição, as setas continuam movendo o cursor normalmente. O `greeting` é o estado vazio (centrado; some quando a conversa começa e NÃO entra no transcript). Dê altura ao container.
 
 ```tsx preview
 <div className="h-96 rounded-lg border">