@softize/opus 9.0.9 → 9.1.0

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

@@ -22,6 +22,7 @@ const runtime = createRuntime({
   data: kyselyData({ db }),            // fornece ctx.db
   auth: makeAuthAdapter(),             // resolve user/tenant/can
   audit: [pgAudit({ pool })],          // trilha de auditoria (N sinks)
+  observability: makeObservability(),  // span ativo + TraceContext vendor-neutral
   storage: fsStorage({ root }),        // fornece ctx.storage (experimental)
   config: { env, i18n: { defaultLocale: 'pt-BR' } },
 })
@@ -42,6 +43,7 @@ await runtime.start()
 | `auth` | `user`/`tenantId`/`can` do contexto | `jwtAuth` — `…/auth/jwt` · `betterAuthSession` — `…/auth/better-auth` |
 | `audit` | trilha por execução de action | `pgAudit` — `…/audit/pg` · `consoleAudit` — `…/audit/console` |
 | `log` | `ctx.log` estruturado | `pinoLogger` — `@softize/opus/log/pino` |
+| `observability` | span ativo + propagação de trace | porta no core; driver opt-in |
 | `eventBus` | `ctx.emit` + **reactions** | `mittEvents` — `@softize/opus/events/mitt` |
 | `queue` | jobs em background | `bullmqQueue` — `@softize/opus/queue/bullmq` |
 | `scheduler` | **schedules** (cron/intervalo) | `nodeCronScheduler` — `@softize/opus/scheduler/node-cron` |
@@ -60,7 +62,22 @@ Fora do runtime, mas parte do protocolo: o harness de teste (`runAction`/`testCo
 
 `user`/`tenantId`/`can` (auth) · `db` (data) · `log` (logger) · `emit` (eventBus) ·
 `storage` (storage) · `ai` (ai) · `provenance` (quem disparou: http, schedule,
-reaction…) · `meta`.
+reaction…) · `trace` (quando configurado) · `meta`.
+
+O core não depende de OpenTelemetry. O `ObservabilityAdapter` envolve actions e reactions
+com `runInSpan`; o `TraceContext` efetivo também segue para resultado, audit e eventos. Os
+envelopes de job recebem o trace da execução que enfileirou; `executeJob()` cria a execução
+filha no worker sem reenfileirar a action.
+Falha de instrumentação é lenient e nunca repete o handler.
+
+O core não extrai headers HTTP. Os drivers Fastify e Node podem fornecer
+`ContextBase.trace` com `traceContext: 'w3c'`; o opt-in é desativado por default. Outros
+transportes continuam responsáveis por sua fronteira. Em audit, o contexto novo usa
+`traceContext`; o campo `trace` legado continua disponível sem mudança.
+
+Para actions, o callback observável resolve com `ActionResult`: `resultKind: 'action-result'`
+indica que o driver deve inspecionar `result.ok`. Uma Promise resolvida com `ok:false` ainda
+representa span de erro. Reactions usam `resultKind: 'void'` e rejeitam em falha.
 
 ## Reactions e schedules