@softize/opus 9.0.9 → 9.1.0

package/CHANGELOG.md

@@ -11,6 +11,33 @@ Depois de qualquer bump, rode os gates (`typecheck` · `test` · `opus check` ·
 > tinha ficado sem registro nenhum, o que é exatamente o caso que este arquivo existe
 > pra cobrir.
 
+## 9.1.0 — 2026-08-19
+
+**Observabilidade ganha uma porta vendor-neutral no runtime.** `ObservabilityAdapter`
+executa actions e reactions dentro de um span ativo sem acoplar o core a OpenTelemetry.
+`TraceContext` passa de forma opcional por contextos, resultados, `AuditRecord.traceContext`,
+eventos e envelopes de job fornecidos pelo chamador;
+falhas do adapter são lenient e nunca repetem nem substituem o resultado da action.
+
+`AuditRecord.trace` e as colunas PostgreSQL legadas permanecem inalterados. O carrier novo
+não inclui baggage arbitrário. Os drivers Fastify e Node oferecem propagação HTTP W3C opt-in
+com `traceContext: 'w3c'`: `traceparent` v00 entra como parent e o contexto efetivo é emitido
+na resposta; o default legado não lê nem escreve esses headers. Causalidade runtime→job
+não depende mais de montagem manual do envelope: actions `background` são enfileiradas por
+`execute()`, e o worker usa `executeJob()` para executar um span filho sem reenfileirar.
+O carrier desserializado é revalidado por allowlist; o actor reidratado deve coincidir com o
+envelope. BullMQ mapeia attempts, backoff nativo e prioridade sem simular opções incompatíveis.
+
+`pgAudit({ traceContextColumns: true })` persiste opt-in em `trace_id`/`span_id`; sem a
+opção, o INSERT legado continua com 17 colunas e não exige migration. Nomes customizados
+permitem rollout gradual. Operações observáveis declaram `resultKind`: drivers devem
+inspecionar `ActionResult.ok` para actions, pois erro de negócio resolve com `ok:false`.
+
+**Driver OpenTelemetry opt-in.** O subpath
+`@softize/opus/observability/opentelemetry` implementa a porta usando apenas a API OTel e
+aceita `Tracer`, health e shutdown injetados. Provider, context manager, sampling, resource,
+OTLP exporter e Collector continuam sob controle do app; nenhum backend acompanha o SDK.
+
 ## 9.0.9 — 2026-08-19
 
 **O composer do `Chat` passa a navegar pelas mensagens já enviadas.** Com o campo vazio,

package/README.md

@@ -104,8 +104,8 @@ pnpm test:cov       # com coverage report
 
 ## Publicar
 
-Publicado no registry compartilhado da Softize (`registry.softize.com.br`), não no
-npm público. `pnpm release [patch|minor|major|x.y.z]` bumpa + publica. Passo a passo
+Publicado no npm público (`registry.npmjs.org`). `pnpm release
+[patch|minor|major|x.y.z]` bumpa + publica. Passo a passo
 (verificar, testar local, auth) em [docs/releasing.md](docs/releasing.md).
 
 ## Licença

package/docs/adr/0001-vendor-neutral-observability-context.md

@@ -0,0 +1,96 @@
+# ADR 0001 — Contexto de observabilidade vendor-neutral no runtime
+
+- Status: aceita
+- Data: 2026-08-18
+
+## Contexto e forças
+
+Actions já carregam identidade de execução, provenance, audit e eventos. Falta, porém, uma porta única para criar um span ativo e
+um contexto de trace coerente entre essas fronteiras. A lacuna força integrações a acoplar o
+core a um SDK de APM, instrumentar handlers por fora ou esconder trace em `meta`, impedindo
+interoperabilidade e tornando audit/eventos/jobs divergentes.
+
+O contrato precisa:
+
+- manter o core sem dependência de OpenTelemetry ou de qualquer vendor;
+- permitir que o handler execute dentro do mecanismo de contexto ativo do driver;
+- propagar a mesma identidade de trace em `ActionContext`, `ActionResult`, audit,
+  eventos e reactions;
+- preservar a causalidade pai→filho sem confundir `requestId` com `traceId`;
+- não repetir efeitos nem mudar sucesso/erro da action quando a instrumentação falhar;
+- deixar atributos, sampling, exportação e backend sob responsabilidade do driver.
+
+## Alternativas consideradas
+
+### Instrumentar diretamente com OpenTelemetry no runtime
+
+Entrega contexto ativo e um ecossistema pronto, mas adiciona dependência e semântica de um
+vendor/API específica ao protocolo. Também obriga consumidores que não usam OTel a carregar
+essa escolha. Rejeitada para o core; um driver separado continua possível.
+
+### Expor somente hooks `onStart`/`onEnd`
+
+É simples e tolerante a falhas, mas não consegue manter um span ativo durante loaders,
+autorização, handler e emits em runtimes com contexto assíncrono. Rejeitada.
+
+### Guardar trace apenas em `meta`
+
+Evita novos tipos, porém não cria contrato interoperável, mistura metadata de negócio com
+propagação e deixa cada envelope com um shape diferente. Rejeitada.
+
+### Porta que envolve a execução
+
+Um `ObservabilityAdapter.runInSpan` recebe uma descrição neutra da operação e chama o
+callback dentro de seu contexto ativo. O callback recebe o `TraceContext` efetivo do span,
+que o runtime distribui pelos envelopes. Aceita.
+
+## Decisão
+
+O core define `TraceContext`, `ObservabilityOperation` e `ObservabilityAdapter` como
+contratos de primeira classe. `TraceContext` contém identificadores e estado de propagação
+neutros; não expõe objetos de span nem APIs de um SDK. O runtime envolve actions e reactions
+com `runInSpan`, passando o trace recebido como `parent` e usando o trace efetivo retornado
+ao callback em:
+
+- `ActionContext.trace` e `ReactionContext.trace`;
+- `ResultMeta.trace` e o novo `AuditRecord.traceContext`; `AuditRecord.trace` legado fica intacto;
+- `DomainEvent.trace`, preservado ao iniciar uma reaction;
+- envelopes `JobSpec.ctx.trace` e `JobHandle.trace`, quando produzidos por código externo.
+
+`requestId` permanece uma identidade de transporte e pode coexistir com trace. Provenance
+continua descrevendo quem/o quê disparou a execução; trace descreve causalidade técnica.
+
+A instrumentação é lenient por contrato do runtime. Se o adapter falhar antes de chamar o
+callback, o runtime executa uma vez sem instrumentação, preservando o trace pai quando houver.
+Se falhar depois de chamar o callback, o runtime preserva o valor ou erro do callback e não o
+executa novamente. O callback entregue ao adapter é memoizado antes de ceder controle; mesmo
+um adapter que o dispare sem aguardar e rejeite em paralelo recebe sempre a mesma Promise.
+A falha de instrumentação é registrada no logger. Isso impede que observabilidade altere a
+semântica ou duplique efeitos.
+
+O `TraceContext` público é uma allowlist pequena (`traceId`, `spanId`, `traceFlags`,
+`traceState`); baggage arbitrário não atravessa resultados, audit, eventos ou jobs. O runtime
+não extrai headers HTTP. Em incremento posterior, os drivers Fastify e Node ganharam opt-in
+`traceContext: 'w3c'`: extraem somente `traceparent` v00 válido e `tracestate` limitado para
+`ContextBase.trace`, e injetam o contexto efetivo na resposta. O default permanece desligado;
+outros transportes continuam responsáveis por essa fronteira.
+
+O primeiro incremento não incluiu driver OpenTelemetry. O incremento subsequente adicionou
+um driver API-only em subpath separado, depois das garantias de causalidade e at-most-once
+serem provadas. Exporter, Collector, backend APM e UI continuam fora do SDK.
+
+O sink PostgreSQL conserva o schema legado por default. Persistência de `traceContext` é
+opt-in por `traceContextColumns`, somente depois que o consumer criar colunas novas; os campos
+legados nunca são semanticamente reutilizados. Para actions, `resultKind: 'action-result'`
+avisa o driver de que outcome vem de `ActionResult.ok`, não apenas de resolve/reject.
+
+## Consequências
+
+O protocolo ganha campos opcionais compatíveis com consumidores existentes. O incremento
+subsequente ligou actions `background` ao `QueueAdapter`: `execute()` cria o envelope com o
+trace do enqueue, e `executeJob()` revalida o carrier e cria a execução filha no worker.
+BullMQ persiste o envelope, mas o app continua dono do `Worker` e da reidratação de auth.
+Event bus preserva o campo para reactions. Adapters de
+observabilidade podem implementar contexto ativo com OTel, AsyncLocalStorage ou outro
+mecanismo sem vazar essa escolha. Como o runtime não controla adapters remotos, perda de trace
+por um driver que não persiste o envelope continua detectável, mas não corrigível pelo core.

package/docs/protocol.md

@@ -505,6 +505,7 @@ type ActionContext = {
   db:       unknown;                      // injetado pelo DataAdapter
   log:      LoggerAdapter;                // injetado pelo LoggerAdapter (default console)
   emit:     EmitFn;                       // emite DomainEvent via EventBusAdapter
+  trace?:   TraceContext;                 // span ativo, quando observabilidade está configurada
   storage:  StorageAdapter | null;        // storage de arquivos (experimental; null sem adapter)
   provenance: Provenance;                 // quem disparou (http/schedule/reaction/…)
   meta:     Record<string, unknown>;      // adapter pode estender
@@ -626,10 +627,11 @@ type AuditRecord = {
   error?:  ActionError;       // presente apenas em outcome=error
 
   severity: 'info' | 'warning' | 'error';
-  trace?: {
+  trace?: {                    // campo legado — compatibilidade
     requestId?: string;
-    parentActionId?: string;  // quando esta action é disparada por outra
+    parentActionId?: string;
   };
+  traceContext?: TraceContext; // identidade distribuída do span da action
   meta?: Record<string, unknown>;
 }
 ```
@@ -718,7 +720,7 @@ Falha ao emitir audit **não** falha a action. Sink lançou → opus loga `{ cod
 
 - Logs de debug do handler — usa logger do projeto.
 - Métricas (counter de execuções, latência percentile) — usa observabilidade do projeto.
-- Traces distribuídos — usa OpenTelemetry no adapter; opus só carrega `trace.requestId` se o adapter populou.
+- Exportação de traces — pertence ao `ObservabilityAdapter`; audit apenas preserva `TraceContext`.
 - Replay de actions — audit não foi desenhado pra reexecução. Event sourcing é outro contrato.
 
 ---
@@ -741,6 +743,7 @@ type ResultMeta = {
   action:     string;          // nome da action
   durationMs: number;
   requestId?: string;          // trace, populado pelo adapter se disponível
+  trace?:     TraceContext;    // span efetivo da execução
   cached?:    boolean;         // resultado serviu do cache do client
 }
 ```
@@ -924,6 +927,7 @@ Core do Opus é **abstrato** — não tem HTTP, não tem DB, não tem framework
 | Auth      | `@softize/opus/auth`      | `/better-auth`, `/clerk`                           |
 | Audit     | `@softize/opus/audit`     | `/pg`, `/sentry`, `/console`                       |
 | Logger    | `@softize/opus/log`       | `/pino` (console fica no `core`)                   |
+| Observability | `@softize/opus/observability` | `/opentelemetry` (API-only; exporter é do app) |
 | Queue     | `@softize/opus/queue`     | `/bullmq`, `/inngest`, `/redis`                    |
 | EventBus  | `@softize/opus/events`    | `/mitt` (default), `/redis`, `/nats`               |
 | Client    | `@softize/opus/client`    | `/fetch`, `/tanstack`                              |
@@ -951,7 +955,7 @@ Todo adapter implementa `Adapter`:
 interface Adapter {
   name:    string;
   kind:    'server' | 'data' | 'auth' | 'audit' | 'logger'
-         | 'queue' | 'eventbus' | 'client' | 'ui' | 'schema';
+         | 'queue' | 'eventbus' | 'client' | 'ui' | 'schema' | 'observability';
   init?:        (runtime: Runtime) => Promise<void> | void;
   dispose?:     () => Promise<void> | void;
   healthCheck?: () => Promise<{ ok: boolean, details?: object }>;
@@ -1040,8 +1044,67 @@ interface LoggerAdapter extends Adapter {
   fatal(msg: string, meta?: object): void;
   child(bindings: object): LoggerAdapter;  // pre-bind contexto (per-action, per-request)
 }
+
+type TraceContext = {
+  traceId: string;
+  spanId?: string;
+  traceFlags?: number;
+  traceState?: string;
+}
+
+interface ObservabilityAdapter extends Adapter {
+  kind: 'observability';
+  runInSpan<T>(
+    operation: {
+      name: string;
+      kind: 'action' | 'reaction';
+      resultKind: 'action-result' | 'void';
+      parent?: TraceContext;
+      attributes?: Record<string, string | number | boolean>;
+    },
+    run: (trace: TraceContext) => Promise<T>,
+  ): Promise<T>;
+}
+```
+
+O runtime chama o callback dentro do contexto ativo do driver e propaga o trace recebido.
+Falha do adapter é sempre lenient: antes do callback, a execução segue sem novo span; depois
+do callback, o runtime preserva seu resultado/erro e nunca repete efeitos. Exporters,
+sampling, atributos adicionais e OpenTelemetry pertencem ao driver.
+
+O callback é at-most-once: chamadas concorrentes ou tardias do adapter recebem a mesma
+Promise. `TraceContext` não aceita baggage arbitrário. Na entrada HTTP, o core não interpreta
+headers W3C. Os drivers Fastify e Node oferecem o opt-in `traceContext: 'w3c'`, desativado por
+default, para extrair `traceparent` v00 e `tracestate` limitado e injetar o contexto efetivo
+na resposta. Outros transportes fornecem `ContextBase.trace` em sua própria fronteira.
+
+Outcome não é inferido apenas pela Promise: em `resultKind: 'action-result'`, o callback
+resolve com `ActionResult` e o driver deve inspecionar `result.ok` (`false` é span de erro).
+Em `resultKind: 'void'`, usado por reactions, falha rejeita a Promise.
+
+O driver `@softize/opus/observability/opentelemetry` usa somente `@opentelemetry/api`.
+Provider, context manager, resource, sampling e exporter OTLP são configurados pelo app.
+Ele allowlista atributos de baixa cardinalidade e não grava input/output, actor, tenant,
+request ID, códigos/mensagens de erro ou baggage no span.
+
+### Persistência PostgreSQL de trace
+
+O `pgAudit` mantém por default o INSERT legado e não exige migration. Para materializar
+`AuditRecord.traceContext`, o consumer adiciona colunas próprias e habilita explicitamente:
+
+```sql
+ALTER TABLE audit_log ADD COLUMN trace_id text;
+ALTER TABLE audit_log ADD COLUMN span_id text;
+```
+
+```ts
+pgAudit({ pool, traceContextColumns: true })
 ```
 
+Durante rollout, nomes customizados são aceitos com
+`traceContextColumns: { traceId: 'otel_trace_id', spanId: 'otel_span_id' }`. As colunas
+legadas `trace_request_id`/`trace_parent_action_id` nunca recebem `traceId`/`spanId`.
+
 Ver §10 (Background), §11 (Eventos), §15 (RuntimeConfig) para detalhes de uso.
 
 ### Server endpoints (auto-mount)
@@ -1098,6 +1161,7 @@ const runtime = createRuntime({
   audit:     [pgAuditSink({ table: 'audit_log' })],
   queue:     bullmqAdapter({ connection }),       // opcional — só se houver background action
   eventBus:  mittEventBusAdapter(),               // opcional — só se houver emits
+  observability: observabilityAdapter(),           // opcional — porta vendor-neutral
 })
 
 runtime.register(actions)            // monta tudo
@@ -1313,7 +1377,31 @@ type JobHandle<T = unknown> = {
   startedAt?:   string
   finishedAt?:  string
   attempts:     number
+  trace?:       TraceContext
+}
+```
+
+O runtime enfileira actions background em `execute()`. O `JobSpec` recebe request ID, actor,
+tenant, provenance original e o trace efetivo do span de enqueue. No worker, `executeJob()`
+revalida o carrier, exige que o actor reidratado coincida com o envelope e executa um span
+filho sem reenfileirar a action.
+
+```ts
+type JobSpec = {
+  jobId: string
+  action: string
+  input: unknown
+  ctx: {
+    userId: string | null
+    tenantId: string | null
+    requestId?: string
+    trace?: TraceContext
+    originalProvenance?: Provenance
+  }
+  config: BackgroundConfig
 }
+
+runtime.executeJob(spec, rehydratedContext, progressReporter?)
 ```
 
 ActionResult de background action:
@@ -1329,18 +1417,17 @@ type BackgroundResult<T> =
 ```
 HTTP request → Server adapter
   ↓ (1) validate input
-  ↓ (2) authenticate
-  ↓ (3) authorize (sem load — load roda no worker)
-  ↓ (4) enqueue job via QueueAdapter
+  ↓ (2) load + authenticate + authorize
+  ↓ (3) enqueue job via QueueAdapter + audit do enqueue
   ↓
 Server retorna JobHandle síncrono → client polla ou subscribe
   ↓
 Worker (processo separado) consome job:
-  ↓ (a) load
-  ↓ (b) handler (recebe ProgressReporter se config.progress)
-  ↓ (c) validate output
-  ↓ (d) audit
-  ↓ (e) atualiza JobHandle.status = done/failed
+  ↓ (a) reidrata auth/can e chama runtime.executeJob(spec, ctx, progress)
+  ↓ (b) revalida input + load + authenticate + authorize
+  ↓ (c) handler (recebe ProgressReporter se config.progress)
+  ↓ (d) validate output + audit com provenance background
+  ↓ (e) processor retorna/lança; BullMQ atualiza status done/failed
 ```
 
 ### Adapter: `QueueAdapter`
@@ -1425,6 +1512,7 @@ type DomainEvent<T = unknown> = {
     actionId:    string                 // bate com AuditRecord.id
     correlation?: string                // request id / trace
   }
+  trace?:    TraceContext                 // propagado para reactions/consumidores
   meta?:     Record<string, unknown>
 }
 ```
@@ -1536,6 +1624,7 @@ type ReactionContext = {
   log:      LoggerAdapter            // logger pre-bound com contexto da reaction
   storage:  StorageAdapter | null    // storage de arquivos (experimental)
   provenance: Provenance             // { kind: 'reaction', … }
+  trace?:   TraceContext             // span filho do evento recebido
   meta:     Record<string, unknown>
 }
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softize/opus",
-  "version": "9.0.9",
+  "version": "9.1.0",
   "description": "End-to-end action protocol for TypeScript. Single package with subpath exports (core + adapters).",
   "license": "MIT",
   "type": "module",
@@ -92,6 +92,14 @@
       "types": "./src/log/drivers/pino.ts",
       "default": "./src/log/drivers/pino.ts"
     },
+    "./observability": {
+      "types": "./src/observability/index.ts",
+      "default": "./src/observability/index.ts"
+    },
+    "./observability/opentelemetry": {
+      "types": "./src/observability/drivers/opentelemetry.ts",
+      "default": "./src/observability/drivers/opentelemetry.ts"
+    },
     "./queue": {
       "types": "./src/queue/index.ts",
       "default": "./src/queue/index.ts"
@@ -222,6 +230,7 @@
     "zod-to-json-schema": "^3.23.0"
   },
   "peerDependencies": {
+    "@opentelemetry/api": "^1.9.0",
     "@anthropic-ai/sdk": ">=0.35.0",
     "@aws-sdk/client-s3": "^3.0.0",
     "@aws-sdk/s3-request-presigner": "^3.0.0",
@@ -240,6 +249,9 @@
     "zod": "^3.24.0"
   },
   "peerDependenciesMeta": {
+    "@opentelemetry/api": {
+      "optional": true
+    },
     "@hookform/resolvers": {
       "optional": true
     },
@@ -294,6 +306,9 @@
     "@aws-sdk/client-s3": "^3.0.0",
     "@aws-sdk/s3-request-presigner": "^3.0.0",
     "@hookform/resolvers": "^3.10.0",
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/context-async-hooks": "^2.10.0",
+    "@opentelemetry/sdk-trace-base": "^2.10.0",
     "@tanstack/react-query": "^5.62.0",
     "@testing-library/dom": "^10.4.0",
     "@testing-library/react": "^16.1.0",

package/src/audit/drivers/pg.ts

@@ -22,6 +22,12 @@
  *     trace_parent_action_id  text,
  *     meta            jsonb
  *   );
+ *
+ * Para persistir `AuditRecord.traceContext`, adicione colunas novas e opte explicitamente:
+ *
+ *   ALTER TABLE audit_log ADD COLUMN trace_id text;
+ *   ALTER TABLE audit_log ADD COLUMN span_id text;
+ *   pgAudit({ pool, traceContextColumns: true })
  *   CREATE INDEX audit_provenance_kind_idx ON audit_log(provenance_kind);
  *
  * Tabela é criada pelo consumer (migration). Adapter apenas insere.
@@ -61,6 +67,16 @@ export interface PgAuditOptions {
   /** Nome do sink (default 'pg'). */
   name?: string
 
+  /**
+   * Opt-in para persistir `AuditRecord.traceContext` sem quebrar tabelas legadas.
+   * `true` usa `trace_id`/`span_id`; objeto permite nomes customizados durante rollout.
+   * Default `false`: mantém exatamente o INSERT legado de 17 colunas.
+   */
+  traceContextColumns?: boolean | {
+    traceId?: string
+    spanId?: 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
@@ -74,14 +90,21 @@ export interface PgAuditOptions {
 export function pgAudit(options: PgAuditOptions): AuditSink {
   const { pool, table = 'audit_log', name = 'pg', redact } = options
   validateTableName(table)
-  const sql = buildInsertSql(table)
+  const traceColumns = resolveTraceColumns(options.traceContextColumns)
+  const columns = traceColumns === undefined
+    ? [...LEGACY_COLUMNS]
+    : [...LEGACY_COLUMNS, traceColumns.traceId, traceColumns.spanId]
+  const sql = buildInsertSql(table, columns)
 
   return {
     name,
     kind: 'audit',
 
     async emit(record: AuditRecord) {
-      const values = recordToValues(redact === undefined ? record : redactRecord(record, redact))
+      const values = recordToValues(
+        redact === undefined ? record : redactRecord(record, redact),
+        traceColumns !== undefined,
+      )
       await pool.query(sql, values)
     },
 
@@ -100,7 +123,7 @@ export function pgAudit(options: PgAuditOptions): AuditSink {
 // SQL builder
 // =============================================================================
 
-const COLUMNS = [
+const LEGACY_COLUMNS = [
   'id',
   'timestamp',
   'action',
@@ -120,14 +143,14 @@ const COLUMNS = [
   'meta',
 ] as const
 
-function buildInsertSql(table: string): string {
-  const cols = COLUMNS.join(', ')
-  const params = COLUMNS.map((_, i) => `$${i + 1}`).join(', ')
+function buildInsertSql(table: string, columns: 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 [
+function recordToValues(r: AuditRecord, includeTraceContext: boolean): unknown[] {
+  const values: unknown[] = [
     r.id,
     r.timestamp,
     r.action,
@@ -146,6 +169,29 @@ function recordToValues(r: AuditRecord): unknown[] {
     r.trace?.parentActionId ?? null,
     jsonOrNull(r.meta),
   ]
+  if (includeTraceContext) {
+    values.push(r.traceContext?.traceId ?? null, r.traceContext?.spanId ?? null)
+  }
+  return values
+}
+
+function resolveTraceColumns(
+  option: PgAuditOptions['traceContextColumns'],
+): { traceId: string; spanId: string } | undefined {
+  if (option === undefined || option === false) return undefined
+  const columns = option === true
+    ? { traceId: 'trace_id', spanId: 'span_id' }
+    : { traceId: option.traceId ?? 'trace_id', spanId: option.spanId ?? 'span_id' }
+  validateColumnName(columns.traceId)
+  validateColumnName(columns.spanId)
+  if (columns.traceId === columns.spanId) {
+    throw new Error('pgAudit: traceContext column names must be distinct')
+  }
+  if (LEGACY_COLUMNS.includes(columns.traceId as (typeof LEGACY_COLUMNS)[number]) ||
+      LEGACY_COLUMNS.includes(columns.spanId as (typeof LEGACY_COLUMNS)[number])) {
+    throw new Error('pgAudit: traceContext columns must not overlap legacy columns')
+  }
+  return columns
 }
 
 function jsonOrNull(value: unknown): string | null {
@@ -170,3 +216,9 @@ function validateTableName(table: string): void {
     )
   }
 }
+
+function validateColumnName(column: string): void {
+  if (!/^[a-z_][a-z0-9_]*$/i.test(column)) {
+    throw new Error(`pgAudit: invalid column name "${column}"`)
+  }
+}

package/src/core/actions.ts

@@ -102,7 +102,9 @@ export function isViewAction(
 /**
  * `true` se a action declarou execução em background (apenas `simple` e `form`).
  */
-export function isBackgroundAction(action: ActionDef): boolean {
+export function isBackgroundAction(
+  action: ActionDef,
+): action is SimpleAction<any, any> | FormAction<any, any> {
   return (
     (action.kind === 'simple' || action.kind === 'form') &&
     action.background?.enabled === true

package/src/core/index.ts

@@ -9,6 +9,7 @@ export type {
   // primitivos / shared
   I18nRef,
   Unsubscribe,
+  TraceContext,
   Logger,
   ContextBase,
   Schema,
@@ -91,6 +92,8 @@ export type {
   AuthAdapter,
   AuditSink,
   LoggerAdapter,
+  ObservabilityAdapter,
+  ObservabilityOperation,
   QueueAdapter,
   EventBusAdapter,
   SchedulerAdapter,
@@ -123,6 +126,7 @@ export type {
 // — Erro ——————————————————————————————————————————————————————————————————————
 export { error, isActionError, normalizeError } from './errors.ts'
 export type { ErrorInput } from './errors.ts'
+export { normalizeTraceContext } from './trace.ts'
 
 // — Logical types ——————————————————————————————————————————————————————————————
 // As factories `t.*` moram em `@softize/opus/schema`; o attach/get da meta é