@softize/opus 9.0.8 → 9.1.0

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

@@ -1,6 +1,6 @@
 ## Básico
 
-A caixa de escrever da casa: textarea numa pílula elevada (`rounded-card` + `border` + `shadow-sm`), **Enter** envia / **Shift+Enter** quebra linha, enviar dentro. É o composer do [Chat](/components/chat) extraído — use SOZINHO quando há entrada de texto mas não um chat (ex.: criar uma sessão). Controlado: o dono do texto é você.
+A caixa de escrever da casa: textarea numa pílula elevada (`rounded-card` + `border` + `shadow-sm`), **Enter** envia / **Shift+Enter** quebra linha, enviar dentro. É o composer do [Chat](/components/chat) extraído — use SOZINHO quando há entrada de texto mas não um chat (ex.: criar uma sessão). Controlado: o dono do texto é você. Os callbacks opcionais `onHistoryPrevious` e `onHistoryNext` permitem que esse dono consuma **↑/↓**; sem eles, as setas mantêm o comportamento nativo da textarea.
 
 ```tsx preview col
 const [text, setText] = React.useState('')

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

@@ -0,0 +1,71 @@
+---
+title: Observabilidade
+---
+
+# Observabilidade
+
+O core expõe uma porta vendor-neutral; o driver OpenTelemetry cria spans ativos para actions
+e reactions sem escolher backend, exporter ou Collector.
+
+## Driver OpenTelemetry
+
+Configure o SDK antes de criar o runtime. Exemplo com OTLP/HTTP apontando para um Collector:
+
+```ts
+import { NodeSDK } from '@opentelemetry/sdk-node'
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http'
+import { openTelemetryObservability } from '@softize/opus/observability/opentelemetry'
+import { createRuntime } from '@softize/opus/core'
+
+const sdk = new NodeSDK({
+  traceExporter: new OTLPTraceExporter({
+    url: 'http://otel-collector:4318/v1/traces',
+  }),
+})
+await sdk.start()
+
+const runtime = createRuntime({
+  observability: openTelemetryObservability({
+    shutdown: () => sdk.shutdown(),
+  }),
+})
+```
+
+O app é dono do `NodeSDK`, sampling, resource (`service.name`), exporter, autenticação e
+retry. A opção `shutdown` é explícita: sem ela, `runtime.dispose()` não desliga o provider
+global. Um `Tracer` também pode ser injetado para testes ou providers não globais.
+
+## Semântica
+
+- nomes de span: `opus.action <action>` e `opus.reaction <reaction>`;
+- parent vem de `ContextBase.trace` ou do evento recebido;
+- actions usam `ActionResult.ok` para status; reactions usam resolve/reject;
+- somente atributos allowlisted de baixa cardinalidade são anexados;
+- input, output, actor, tenant, request ID, error code/message e baggage não entram no span;
+- `TraceContext` devolve apenas `traceId`, `spanId`, `traceFlags` e `traceState`.
+
+## Fronteira HTTP W3C
+
+Os drivers Fastify e Node oferecem propagação explícita, desativada por default:
+
+```ts
+fastifyServer({ app, traceContext: 'w3c' })
+nodeServer({ traceContext: 'w3c' })
+```
+
+O opt-in extrai um `traceparent` v00 válido (e `tracestate` limitado) para
+`ContextBase.trace`. Depois da action, injeta na resposta o `traceparent` do contexto
+efetivo retornado pelo runtime. `baggage` nunca é lido nem copiado. Headers inválidos são
+ignorados; sem a opção, os drivers mantêm o comportamento anterior e não interpretam nem
+emitem contexto de trace.
+
+## Limites
+
+O driver OpenTelemetry não instrumenta HTTP automaticamente e não oferece backend APM.
+Use o opt-in dos drivers Fastify/Node acima ou forneça `ContextBase.trace` na instrumentação
+de outro transporte. A fronteira implementa somente `traceparent` v00 e uma validação
+defensiva limitada de `tracestate`; não é um propagator OTel genérico.
+Health do exporter/Collector só é reportado quando o app injeta `healthCheck`; o default
+confirma apenas que a API do driver está configurada.
+Sem um provider que produza spans válidos, o driver falha antes do callback e o runtime aplica
+a degradação lenient — executa a action uma vez, sem trace — em vez de propagar IDs inválidos.

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

@@ -25,11 +25,14 @@ interface JobHandle<T = unknown> {
   data?: T
   error?: ActionError
   attempts: number
+  trace?: TraceContext
 }
 ```
 
-O core monta o `JobSpec` (action, input, ctx, retry/priority/timeout); o adapter persiste e
-processa.
+`runtime.execute()` valida a chamada, cria o `JobSpec` e inclui o trace efetivo, request ID e
+provenance original. O adapter persiste o envelope; o handle também expõe esse trace. No
+worker, `runtime.executeJob()` revalida o envelope e executa um span filho, preservando a
+cadeia request → enqueue → job sem aceitar baggage ou campos extras no carrier.
 
 ## Driver
 
@@ -52,10 +55,33 @@ const runtime = createRuntime({
 })
 ```
 
-A action declara `background: true` (+ retry/priority no contrato); chamá-la devolve um
+A action declara `background: { enabled: true }` (+ retry/priority no contrato); chamá-la devolve um
 `JobHandle` em vez do resultado, e o cliente pola `status(jobId)` (ou `subscribe`) até
 `done`/`failed`.
 
+## Worker BullMQ
+
+O app continua dono do `Worker` e da reidratação de autenticação. O processor chama
+`executeJob()` — nunca `execute()`, que criaria outro job:
+
+```ts
+new Worker('opus', async (job) => {
+  const spec = job.data as JobSpec
+  const ctx = await authContextForJob(spec.ctx)
+  const result = await runtime.executeJob(spec, ctx, {
+    report: (progress) => job.updateProgress(progress),
+  })
+  if (!result.ok) throw new Error(result.error.message)
+  return result.data
+}, { connection })
+```
+
+O runtime confirma que o actor reidratado corresponde a `spec.ctx.userId`; tenant, request,
+trace e provenance vêm do envelope. O driver mapeia `attempts`, backoff nativo e prioridade.
+Multiplicador exponencial diferente de 2 ou `maxMs` exige `backoffStrategy` custom do worker e
+é rejeitado pelo driver em vez de ser silenciosamente ignorado. `timeout` permanece no
+envelope para o worker aplicar, pois não é uma opção de execução do `Queue.add`.
+
 ## Limites (por enquanto)
 
 Driver hoje: `bullmq` (Redis). In-memory pra dev e outros backends (SQS, pg-boss…) entram

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