@softize/opus 9.0.9 → 9.1.0

package/src/core/runtime.ts

@@ -12,11 +12,13 @@
  */
 
 import { isReaction } from './reactions.ts'
+import { isBackgroundAction } from './actions.ts'
 import { isSchedule } from './schedules.ts'
 import { collectDomainWarnings, flattenDomain, isDomainConfig } from './domain.ts'
 import type { DomainConfig } from './domain.ts'
 import { AuditEmitter } from './audit.ts'
 import { error, isActionError, normalizeError } from './errors.ts'
+import { normalizeTraceContext } from './trace.ts'
 import { evalExpression } from '../dsl/eval.ts'
 import { parseExpression } from '../dsl/parser.ts'
 import { parseLoad, resolveLoadArgs } from '../dsl/loads.ts'
@@ -40,12 +42,16 @@ import type {
   EventBusAdapter,
   HealthStatus,
   I18nRef,
+  JobSpec,
   LoaderFn,
   LoaderResolver,
   LoadsSpec,
   Logger,
   LoggerAdapter,
+  ObservabilityAdapter,
+  ObservabilityOperation,
   Provenance,
+  ProgressReporter,
   QueueAdapter,
   ReactionContext,
   ReactionDef,
@@ -62,6 +68,7 @@ import type {
   AiTool,
   AIConfig,
   User,
+  TraceContext,
 } from './types.ts'
 
 /* eslint-disable @typescript-eslint/no-explicit-any */
@@ -82,6 +89,7 @@ export interface RuntimeSetup {
   data?: DataAdapter
   auth?: AuthAdapter
   logger?: LoggerAdapter
+  observability?: ObservabilityAdapter
   audit?: AuditSink | AuditSink[]
   queue?: QueueAdapter
   eventBus?: EventBusAdapter
@@ -229,6 +237,7 @@ export class Runtime {
   private readonly server: ServerAdapter | undefined
   private readonly data: DataAdapter | undefined
   private readonly logger: LoggerAdapter | undefined
+  private readonly observability: ObservabilityAdapter | undefined
   private readonly queue: QueueAdapter | undefined
   private readonly eventBus: EventBusAdapter | undefined
   private readonly scheduler: SchedulerAdapter | undefined
@@ -267,6 +276,7 @@ export class Runtime {
   constructor(setup: RuntimeSetup) {
     this.config = applyConfigDefaults(setup.config)
     this.logger = setup.logger
+    this.observability = setup.observability
     this.log = setup.logger ?? new ConsoleLogger({ runtime: 'tbdlib' })
 
     this.audit = new AuditEmitter({ mode: this.config.auditMode, log: this.log })
@@ -488,10 +498,7 @@ export class Runtime {
     return { ok, adapters }
   }
 
-  /**
-   * Executa uma action de forma síncrona. Background actions usam
-   * `executeBackground` (não implementado em v0; queue adapter dispara).
-   */
+  /** Executa uma action; declarations background são validadas e enfileiradas. */
   async execute(
     actionName: string,
     input: unknown,
@@ -506,11 +513,81 @@ export class Runtime {
       }), 0, ctxBase.requestId)
     }
 
+    return this.executeAction(action, input, ctxBase, 'request')
+  }
+
+  /**
+   * Executa no worker um envelope criado por `execute()`. O consumer fornece
+   * auth/can reidratados; identidade, provenance e trace vêm do envelope.
+   */
+  async executeJob(
+    spec: JobSpec,
+    ctxBase: ContextBase,
+    progress?: ProgressReporter,
+  ): Promise<ActionResult<unknown>> {
+    const action = this.actions.get(spec.action)
+    if (action === undefined) {
+      return this.errorResult(spec.action, error({
+        code: 'runtime.action_not_found',
+        category: 'not_found',
+        message: `Action "${spec.action}" is not registered`,
+      }), 0, spec.ctx.requestId)
+    }
+    if (!isBackgroundAction(action)) {
+      return this.errorResult(spec.action, error({
+        code: 'runtime.action_not_background',
+        category: 'validation',
+        message: `Action "${spec.action}" is not declared as background`,
+      }), 0, spec.ctx.requestId)
+    }
+    if ((ctxBase.user?.id ?? null) !== spec.ctx.userId) {
+      return this.errorResult(spec.action, error({
+        code: 'runtime.job_actor_mismatch',
+        category: 'authentication',
+        message: 'Worker context actor does not match the job envelope',
+      }), 0, spec.ctx.requestId)
+    }
+
+    const trace = normalizeTraceContext(spec.ctx.trace)
+    return this.executeAction(action, spec.input, {
+      ...ctxBase,
+      tenantId: spec.ctx.tenantId,
+      ...(spec.ctx.requestId !== undefined ? { requestId: spec.ctx.requestId } : {}),
+      ...(trace !== undefined ? { trace } : {}),
+      provenance: {
+        kind: 'background',
+        queueName: spec.config.queue ?? 'default',
+        jobId: spec.jobId,
+        ...(spec.ctx.originalProvenance !== undefined
+          ? { originalProvenance: spec.ctx.originalProvenance }
+          : {}),
+      },
+    }, 'job', progress)
+  }
+
+  private async executeAction(
+    action: ActionDef,
+    input: unknown,
+    ctxBase: ContextBase,
+    execution: 'request' | 'job',
+    progress?: ProgressReporter,
+  ): Promise<ActionResult<unknown>> {
+
     const startedAt = performance.now()
     const actionId = generateId()
-    const ctx = this.buildActionContext(action, actionId, ctxBase)
+    return this.runObserved(
+      {
+        name: action.name,
+        kind: 'action',
+        resultKind: 'action-result',
+        ...(ctxBase.trace !== undefined ? { parent: ctxBase.trace } : {}),
+        attributes: { 'opus.action.id': actionId, 'opus.action.kind': action.kind },
+      },
+      ctxBase.trace,
+      async (trace) => {
+        const ctx = this.buildActionContext(action, actionId, ctxBase, trace)
 
-    try {
+        try {
       // — 1. Validate input ————————————————————————————————————————————————
       const validatedInput = await this.validate(action.input, input, 'input')
 
@@ -540,6 +617,60 @@ export class Runtime {
         if (decision !== true) throw decision
       }
 
+      if (execution === 'request' && isBackgroundAction(action)) {
+        if (this.queue === undefined) {
+          throw error({
+            code: 'runtime.queue_required',
+            category: 'internal',
+            message: `Background action "${action.name}" requires a QueueAdapter`,
+          })
+        }
+        const background = action.background
+        if (background === undefined) {
+          throw error({
+            code: 'runtime.invalid_background_config',
+            category: 'internal',
+            message: `Background action "${action.name}" has no background config`,
+          })
+        }
+        const spec: JobSpec = {
+          jobId: generateId(),
+          action: action.name,
+          input: validatedInput,
+          ctx: {
+            userId: ctx.user?.id ?? null,
+            tenantId: ctx.tenantId,
+            ...(ctxBase.requestId !== undefined ? { requestId: ctxBase.requestId } : {}),
+            ...(trace !== undefined ? { trace } : {}),
+            originalProvenance: ctx.provenance,
+          },
+          config: {
+            ...(background.queue !== undefined ? { queue: background.queue } : {}),
+            ...(background.priority !== undefined ? { priority: background.priority } : {}),
+            retry: background.retry ?? this.config.defaultRetry,
+            ...(background.timeout !== undefined ? { timeout: background.timeout } : {}),
+          },
+        }
+        const queuedHandle = await this.queue.enqueue(spec)
+        const handle = trace !== undefined ? { ...queuedHandle, trace } : queuedHandle
+        const durationMs = performance.now() - startedAt
+        await this.audit.emit(this.buildAuditRecord({
+          actionId,
+          action: action.name,
+          actionKind: action.kind,
+          outcome: 'success',
+          durationMs,
+          ctx,
+          input: validatedInput,
+          output: handle,
+        }), action.audit)
+        return {
+          ok: true,
+          data: handle,
+          meta: this.buildMeta(actionId, action.name, durationMs, ctxBase.requestId, trace),
+        }
+      }
+
       // — 5. Handler ————————————————————————————————————————————————————————
       // Modo design (`OPUS_MODE=design`): tenta mockHandler primeiro, cai
       // no handler real se não houver. Em qualquer outro modo, handler real
@@ -550,7 +681,14 @@ export class Runtime {
         isDesignMode && action.mockHandler !== undefined
           ? action.mockHandler
           : action.handler
-      const output = await handlerToRun(ctx, validatedInput, loaded)
+      const output = await handlerToRun(
+        ctx,
+        validatedInput,
+        loaded,
+        execution === 'job' && isBackgroundAction(action) && action.background?.progress === true
+          ? progress
+          : undefined,
+      )
       const usedMock = handlerToRun === action.mockHandler
 
       // — 6. Validate output (dev only) —————————————————————————————————————
@@ -583,9 +721,9 @@ export class Runtime {
       return {
         ok: true,
         data: validatedOutput,
-        meta: this.buildMeta(actionId, action.name, durationMs, ctxBase.requestId),
+        meta: this.buildMeta(actionId, action.name, durationMs, ctxBase.requestId, trace),
       }
-    } catch (thrown) {
+        } catch (thrown) {
       const actionError = normalizeError(thrown)
       const durationMs = performance.now() - startedAt
       await this.audit.emit(
@@ -604,9 +742,11 @@ export class Runtime {
       return {
         ok: false,
         error: actionError,
-        meta: this.buildMeta(actionId, action.name, durationMs, ctxBase.requestId),
+        meta: this.buildMeta(actionId, action.name, durationMs, ctxBase.requestId, trace),
       }
-    }
+        }
+      },
+    )
   }
 
   // ===========================================================================
@@ -615,6 +755,7 @@ export class Runtime {
 
   private *allAdapters(): IterableIterator<Adapter> {
     if (this.logger !== undefined) yield this.logger
+    if (this.observability !== undefined) yield this.observability
     if (this.data !== undefined) yield this.data
     if (this.auth !== undefined) yield this.auth
     if (this.server !== undefined) yield this.server
@@ -698,6 +839,7 @@ export class Runtime {
     action: ActionDef,
     actionId: string,
     base: ContextBase,
+    trace: TraceContext | undefined,
   ): ActionContext {
     const dbExt = this.data?.contextExtension() ?? { db: undefined }
     const provenance = resolveProvenance(base)
@@ -716,10 +858,11 @@ export class Runtime {
       can: base.can,
       db: dbExt.db,
       log,
-      emit: this.buildEmit(action, actionId, base),
+      emit: this.buildEmit(action, actionId, base, trace),
       storage: this.storage ?? null,
-      ai: this.bindAi(base),
+      ai: this.bindAi({ ...base, ...(trace !== undefined ? { trace } : {}) }),
       provenance,
+      ...(trace !== undefined ? { trace } : {}),
       meta: base.meta ?? {},
     }
   }
@@ -728,6 +871,7 @@ export class Runtime {
     action: ActionDef,
     actionId: string,
     base: ContextBase,
+    trace: TraceContext | undefined,
   ): ActionContext['emit'] {
     return async (event, data, meta) => {
       if (
@@ -769,6 +913,7 @@ export class Runtime {
           actionId,
           ...(meta?.correlation !== undefined ? { correlation: meta.correlation } : {}),
         },
+        ...(trace !== undefined ? { trace } : {}),
         ...(meta !== undefined ? { meta: meta as Record<string, unknown> } : {}),
       }
 
@@ -933,6 +1078,7 @@ export class Runtime {
       tenant: args.ctx.tenantId,
       input: args.input,
       severity: args.outcome === 'success' ? 'info' : severityForError(args.error),
+      ...(args.ctx.trace !== undefined ? { traceContext: args.ctx.trace } : {}),
     }
     if (args.output !== undefined) record.output = args.output
     if (args.error !== undefined) record.error = args.error
@@ -945,6 +1091,7 @@ export class Runtime {
     actionName: string,
     durationMs: number,
     requestId?: string,
+    trace?: TraceContext,
   ): ResultMeta {
     const meta: ResultMeta = {
       actionId,
@@ -952,6 +1099,7 @@ export class Runtime {
       durationMs,
     }
     if (requestId !== undefined) meta.requestId = requestId
+    if (trace !== undefined) meta.trace = trace
     return meta
   }
 
@@ -1021,15 +1169,27 @@ export class Runtime {
       sourceActionId: event.source.actionId,
       eventType: event.type,
     }
-    const ctx: ReactionContext = {
+    const reactionLog = this.log.child({
+      reaction: reaction.name,
+      eventType: event.type,
+      provenance: 'reaction',
+    })
+    try {
+      await this.runObserved(
+      {
+        name: reaction.name,
+        kind: 'reaction',
+        resultKind: 'void',
+        ...(event.trace !== undefined ? { parent: event.trace } : {}),
+        attributes: { 'opus.event.type': event.type, 'opus.source.action_id': event.source.actionId },
+      },
+      event.trace,
+      async (trace) => {
+        const ctx: ReactionContext = {
       user: event.actor.id !== null ? ({ id: event.actor.id } as User) : null,
       tenantId: event.tenant ?? null,
       db: this.data?.contextExtension().db,
-      log: this.log.child({
-        reaction: reaction.name,
-        eventType: event.type,
-        provenance: 'reaction',
-      }),
+      log: reactionLog,
       emit: noopEmit,
       storage: this.storage ?? null,
       // Reação = contexto de sistema; o agente só alcança actions públicas (can nega por
@@ -1039,31 +1199,75 @@ export class Runtime {
         tenantId: event.tenant ?? null,
         can: async () => false,
         meta: {},
+        ...(trace !== undefined ? { trace } : {}),
       }),
       provenance,
+      ...(trace !== undefined ? { trace } : {}),
       meta: {},
     }
 
-    try {
-      if (reaction.authorize !== undefined) {
-        const allowed = await reaction.authorize(ctx, event)
-        if (!allowed) return
-      }
-      await reaction.handler(ctx, event)
+        if (reaction.authorize !== undefined) {
+          const allowed = await reaction.authorize(ctx, event)
+          if (!allowed) return
+        }
+        await reaction.handler(ctx, event)
+      },
+    )
     } catch (err) {
       const actionError = isActionError(err) ? err : normalizeError(err)
-      ctx.log.error('reaction failed', {
+      reactionLog.error('reaction failed', {
         code: actionError.code,
         message: actionError.message,
       })
     }
   }
+
+  /** Observabilidade nunca repete nem substitui o resultado do callback. */
+  private async runObserved<T>(
+    operation: ObservabilityOperation,
+    fallbackTrace: TraceContext | undefined,
+    run: (trace: TraceContext | undefined) => Promise<T>,
+  ): Promise<T> {
+    if (this.observability === undefined) return run(fallbackTrace)
+
+    let execution: Promise<T> | undefined
+    const executeOnce = (trace: TraceContext | undefined): Promise<T> => {
+      if (execution !== undefined) return execution
+      // Atribui a Promise antes de ceder controle: chamadas concorrentes, tardias ou
+      // malcomportadas do adapter observam a mesma execução e nunca repetem efeitos.
+      execution = Promise.resolve().then(() => run(trace))
+      return execution
+    }
+
+    try {
+      await this.observability.runInSpan(operation, executeOnce)
+    } catch (err) {
+      // Rejeição da própria execução pertence à action/reaction e será devolvida abaixo;
+      // só uma falha antes/depois do callback é falha de instrumentação.
+      if (execution === undefined || await settledSuccessfully(execution)) {
+        this.log.warn('observability adapter failed (lenient)', {
+          operation: operation.name,
+          error: String(err),
+        })
+      }
+    }
+    return executeOnce(fallbackTrace)
+  }
 }
 
 // =============================================================================
 // Helpers
 // =============================================================================
 
+async function settledSuccessfully<T>(promise: Promise<T>): Promise<boolean> {
+  try {
+    await promise
+    return true
+  } catch {
+    return false
+  }
+}
+
 // ContextBase moveu pra types.ts (compartilhado entre core e adapters).
 
 /**

package/src/core/trace.ts

@@ -0,0 +1,34 @@
+import type { TraceContext } from './types.ts'
+
+/** Valida carriers desserializados sem aceitar campos extras ou payload arbitrário. */
+export function normalizeTraceContext(value: unknown): TraceContext | undefined {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return undefined
+  const record = value as Record<string, unknown>
+  const allowed = new Set(['traceId', 'spanId', 'traceFlags', 'traceState'])
+  if (Object.keys(record).some((key) => !allowed.has(key))) return undefined
+  if (
+    typeof record['traceId'] !== 'string' || record['traceId'].length === 0 ||
+    record['traceId'].length > 128
+  ) return undefined
+  if (
+    record['spanId'] !== undefined &&
+    (typeof record['spanId'] !== 'string' || record['spanId'].length === 0 ||
+      record['spanId'].length > 64)
+  ) return undefined
+  if (
+    record['traceFlags'] !== undefined &&
+    (!Number.isInteger(record['traceFlags']) || (record['traceFlags'] as number) < 0 ||
+      (record['traceFlags'] as number) > 255)
+  ) return undefined
+  if (
+    record['traceState'] !== undefined &&
+    (typeof record['traceState'] !== 'string' || record['traceState'].length > 512 ||
+      /[^\x20-\x7e]/.test(record['traceState']))
+  ) return undefined
+  return {
+    traceId: record['traceId'],
+    ...(record['spanId'] !== undefined ? { spanId: record['spanId'] as string } : {}),
+    ...(record['traceFlags'] !== undefined ? { traceFlags: record['traceFlags'] as number } : {}),
+    ...(record['traceState'] !== undefined ? { traceState: record['traceState'] as string } : {}),
+  }
+}

package/src/core/types.ts

@@ -38,6 +38,14 @@ export type I18nRef = string | { key: string; default: string }
  */
 export type Unsubscribe = () => void
 
+/** Contexto de propagação distribuída, independente de SDK/vendor. */
+export interface TraceContext {
+  traceId: string
+  spanId?: string
+  traceFlags?: number
+  traceState?: string
+}
+
 /**
  * Logger genérico que mora no contexto. Implementado por `LoggerAdapter`.
  * Detalhes: §8.
@@ -169,6 +177,7 @@ export interface ResultMeta {
   action: string
   durationMs: number
   requestId?: string
+  trace?: TraceContext
   cached?: boolean
 }
 
@@ -270,6 +279,7 @@ export interface ActionContext {
   storage: StorageAdapter | null
   ai: BoundAi | null
   provenance: Provenance
+  trace?: TraceContext
   meta: Record<string, unknown>
 }
 
@@ -286,6 +296,7 @@ export interface ReactionContext {
   storage: StorageAdapter | null
   ai: BoundAi | null
   provenance: Provenance
+  trace?: TraceContext
   meta: Record<string, unknown>
 }
 
@@ -334,10 +345,13 @@ export interface AuditRecord {
   error?: ActionError
 
   severity: 'info' | 'warning' | 'error'
+  /** Campo legado preservado para compatibilidade com sinks/consumers existentes. */
   trace?: {
     requestId?: string
     parentActionId?: string
   }
+  /** Contexto de trace vendor-neutral; aditivo ao campo `trace` legado. */
+  traceContext?: TraceContext
   meta?: Record<string, unknown>
 }
 
@@ -373,6 +387,7 @@ export interface DomainEvent<T = unknown> {
     actionId: string
     correlation?: string
   }
+  trace?: TraceContext
   meta?: Record<string, unknown>
 }
 
@@ -397,6 +412,7 @@ export interface JobHandle<T = unknown> {
   startedAt?: string
   finishedAt?: string
   attempts: number
+  trace?: TraceContext
 }
 
 /**
@@ -411,6 +427,8 @@ export interface JobSpec {
     userId: string | null
     tenantId: string | null
     requestId?: string
+    trace?: TraceContext
+    originalProvenance?: Provenance
   }
   config: {
     queue?: string
@@ -926,6 +944,7 @@ export type AdapterKind =
   | 'ai'
   | 'ui'
   | 'schema'
+  | 'observability'
 
 /**
  * Resultado de health check de um adapter (ou do runtime agregado).
@@ -964,6 +983,8 @@ export interface ContextBase {
   provenance?: Provenance
   meta?: Record<string, unknown>
   requestId?: string
+  /** Trace pai recebido do transporte, evento ou job. */
+  trace?: TraceContext
 }
 
 /**
@@ -982,6 +1003,11 @@ export interface RuntimeRef {
     input: unknown,
     ctx: ContextBase,
   ): Promise<ActionResult<unknown>>
+  executeJob(
+    spec: JobSpec,
+    ctx: ContextBase,
+    progress?: ProgressReporter,
+  ): Promise<ActionResult<unknown>>
   healthCheck(): Promise<{
     ok: boolean
     adapters: Record<string, HealthStatus>
@@ -1076,6 +1102,24 @@ export interface LoggerAdapter extends Adapter, Logger {
   kind: 'logger'
 }
 
+export interface ObservabilityOperation {
+  name: string
+  kind: 'action' | 'reaction'
+  /** Como o driver determina outcome: action inspeciona `ActionResult.ok`; reaction usa reject. */
+  resultKind: 'action-result' | 'void'
+  parent?: TraceContext
+  attributes?: Record<string, string | number | boolean>
+}
+
+/** Porta de contexto ativo; drivers podem usar OTel, ALS ou outro mecanismo. */
+export interface ObservabilityAdapter extends Adapter {
+  kind: 'observability'
+  runInSpan<T>(
+    operation: ObservabilityOperation,
+    run: (trace: TraceContext) => Promise<T>,
+  ): Promise<T>
+}
+
 export interface QueueAdapter extends Adapter {
   kind: 'queue'
   enqueue(spec: JobSpec): Promise<JobHandle>