@softize/opus 8.6.6

package/src/core/runtime.ts

@@ -0,0 +1,1167 @@
+/**
+ * tbdlib — Runtime
+ *
+ * Orquestrador central. Recebe actions + reactions + adapters + config no setup,
+ * registra cada peça, e executa o pipeline padrão (validate → load → auth →
+ * authorize → handler → audit → result).
+ *
+ * Pipeline interno é privado nesta versão (v0). Se crescer, fatorar em
+ * `pipeline.ts` separado.
+ *
+ * Ver §2, §3, §4, §5, §8, §14 do protocolo.
+ */
+
+import { isReaction } from './reactions.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 { evalExpression } from '../dsl/eval.ts'
+import { parseExpression } from '../dsl/parser.ts'
+import { parseLoad, resolveLoadArgs } from '../dsl/loads.ts'
+import type { AstNode } from '../dsl/types.ts'
+import type { LoadSpec as DslLoadSpec } from '../dsl/loads.ts'
+import type {
+  ActionContext,
+  ActionDef,
+  ActionResult,
+  Adapter,
+  AuditRecord,
+  AuditSink,
+  AuthAdapter,
+  AuthorizeFn,
+  AuthorizeSpec,
+  BackoffSpec,
+  ClientAdapter,
+  ContextBase,
+  DataAdapter,
+  DomainEvent,
+  EventBusAdapter,
+  HealthStatus,
+  I18nRef,
+  LoaderFn,
+  LoaderResolver,
+  LoadsSpec,
+  Logger,
+  LoggerAdapter,
+  Provenance,
+  QueueAdapter,
+  ReactionContext,
+  ReactionDef,
+  ResultMeta,
+  Schema,
+  ScheduleDef,
+  SchedulerAdapter,
+  ServerAdapter,
+  StorageAdapter,
+  AiAdapter,
+  AiRunOptions,
+  BoundAiRunOptions,
+  BoundAi,
+  AiTool,
+  AIConfig,
+  User,
+} from './types.ts'
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+/** Normaliza o `ai` da action (`boolean | AIConfig`) → config, ou null se não exposta à IA. */
+function normalizeAiConfig(ai: boolean | AIConfig | undefined): AIConfig | null {
+  if (ai === undefined || ai === false) return null
+  if (ai === true) return { enabled: true }
+  return ai.enabled === false ? null : ai
+}
+
+// =============================================================================
+// Setup types
+// =============================================================================
+
+export interface RuntimeSetup {
+  server?: ServerAdapter
+  data?: DataAdapter
+  auth?: AuthAdapter
+  logger?: LoggerAdapter
+  audit?: AuditSink | AuditSink[]
+  queue?: QueueAdapter
+  eventBus?: EventBusAdapter
+  scheduler?: SchedulerAdapter
+  client?: ClientAdapter
+  /** EXPERIMENTAL — storage de objetos (arquivos); chega nos handlers via `ctx.storage`. */
+  storage?: StorageAdapter
+  /** EXPERIMENTAL — IA generativa (complete/extract); chega nos handlers via `ctx.ai`. */
+  ai?: AiAdapter
+
+  config?: RuntimeSetupConfig
+}
+
+/**
+ * Subset de `RuntimeConfig` que o usuário passa. Defaults completos são
+ * aplicados internamente em `applyConfigDefaults`.
+ */
+export interface RuntimeSetupConfig {
+  auditMode?: 'lenient' | 'strict'
+  emitMode?: 'lenient' | 'strict'
+  env?: 'development' | 'production' | 'test'
+  dev?: boolean
+  validateOutputInDev?: boolean
+  warnUndeclaredEmits?: boolean
+  dedupCacheTtl?: number
+  defaultRetry?: { attempts: number; backoff?: BackoffSpec }
+  i18n?: {
+    resolver?: (ref: I18nRef, locale?: string) => string
+    defaultLocale?: string
+  }
+  maxConcurrentActions?: number
+  maxConcurrentReactions?: number
+}
+
+/**
+ * `RuntimeConfig` totalmente resolvido (com defaults aplicados).
+ * Acessível via `runtime.config` em adapters.
+ */
+export interface ResolvedRuntimeConfig {
+  auditMode: 'lenient' | 'strict'
+  emitMode: 'lenient' | 'strict'
+  env: 'development' | 'production' | 'test'
+  dev: boolean
+  validateOutputInDev: boolean
+  warnUndeclaredEmits: boolean
+  dedupCacheTtl: number
+  defaultRetry: { attempts: number; backoff?: BackoffSpec }
+  i18n: {
+    resolver?: (ref: I18nRef, locale?: string) => string
+    defaultLocale: string
+  }
+  maxConcurrentActions: number
+  maxConcurrentReactions: number
+}
+
+// =============================================================================
+// Factory
+// =============================================================================
+
+/**
+ * Cria um runtime. Wrapper conveniente sobre `new Runtime(setup)`.
+ */
+export function createRuntime(setup: RuntimeSetup = {}): Runtime {
+  return new Runtime(setup)
+}
+
+// =============================================================================
+// Default console logger
+// =============================================================================
+
+class ConsoleLogger implements Logger {
+  constructor(private readonly bindings: Readonly<Record<string, unknown>> = {}) {}
+
+  trace(msg: string, meta?: object): void {
+    this.write('trace', msg, meta)
+  }
+  debug(msg: string, meta?: object): void {
+    this.write('debug', msg, meta)
+  }
+  info(msg: string, meta?: object): void {
+    this.write('info', msg, meta)
+  }
+  warn(msg: string, meta?: object): void {
+    this.write('warn', msg, meta)
+  }
+  error(msg: string, meta?: object): void {
+    this.write('error', msg, meta)
+  }
+  fatal(msg: string, meta?: object): void {
+    this.write('fatal', msg, meta)
+  }
+
+  child(bindings: object): Logger {
+    return new ConsoleLogger({ ...this.bindings, ...(bindings as object) })
+  }
+
+  private write(level: string, msg: string, meta?: object): void {
+    const merged = { ...this.bindings, ...(meta ?? {}) }
+    const target = level === 'error' || level === 'fatal' ? console.error : console.log
+    /* v8 ignore next — bindings sempre não-vazias quando criado via Runtime */
+    target(`[${level}] ${msg}`, Object.keys(merged).length > 0 ? merged : '')
+  }
+}
+
+// =============================================================================
+// Defaults
+// =============================================================================
+
+function applyConfigDefaults(c: RuntimeSetupConfig = {}): ResolvedRuntimeConfig {
+  const env = c.env ?? 'development'
+  const dev = c.dev ?? env !== 'production'
+  const i18n: ResolvedRuntimeConfig['i18n'] = {
+    defaultLocale: c.i18n?.defaultLocale ?? 'pt-BR',
+  }
+  if (c.i18n?.resolver !== undefined) i18n.resolver = c.i18n.resolver
+
+  return {
+    auditMode: c.auditMode ?? 'lenient',
+    emitMode: c.emitMode ?? 'lenient',
+    env,
+    dev,
+    validateOutputInDev: c.validateOutputInDev ?? dev,
+    warnUndeclaredEmits: c.warnUndeclaredEmits ?? dev,
+    dedupCacheTtl: c.dedupCacheTtl ?? 60_000,
+    defaultRetry: c.defaultRetry ?? {
+      attempts: 3,
+      backoff: { kind: 'exponential', initialMs: 1000 },
+    },
+    i18n,
+    maxConcurrentActions: c.maxConcurrentActions ?? Number.POSITIVE_INFINITY,
+    maxConcurrentReactions: c.maxConcurrentReactions ?? 10,
+  }
+}
+
+// =============================================================================
+// Runtime
+// =============================================================================
+
+export class Runtime {
+  readonly config: ResolvedRuntimeConfig
+  readonly log: Logger
+  readonly audit: AuditEmitter
+  readonly auth: AuthAdapter | undefined
+
+  private readonly server: ServerAdapter | undefined
+  private readonly data: DataAdapter | undefined
+  private readonly logger: LoggerAdapter | undefined
+  private readonly queue: QueueAdapter | undefined
+  private readonly eventBus: EventBusAdapter | undefined
+  private readonly scheduler: SchedulerAdapter | undefined
+  private readonly client: ClientAdapter | undefined
+  private readonly storage: StorageAdapter | undefined
+  private readonly ai: AiAdapter | undefined
+  /** Cache das tools derivadas das actions `ai:enabled` (registry é estático pós-start). */
+  private aiToolsCache: AiTool[] | null = null
+
+  private readonly actions = new Map<string, ActionDef>()
+  private readonly reactions = new Map<string, ReactionDef<any>>()
+  private readonly schedules = new Map<string, ScheduleDef>()
+
+  /**
+   * Map entidade → resolver, usado pra carregar specs DSL de loads
+   * (`'ticket(:id)'`). Registrado via `registerLoaders`. Closures
+   * em `action.loads` não passam por aqui.
+   */
+  private readonly loaderResolvers = new Map<string, LoaderResolver>()
+
+  /**
+   * Cache de AST de DSL `authorize` indexado por string crua. Parsing é
+   * idempotente; evita refazer toda execução.
+   */
+  private readonly authorizeAstCache = new Map<string, AstNode>()
+
+  /**
+   * Cache equivalente pra DSL de `loads` — chave é o spec string crua;
+   * valor é o `LoadSpec` parseado.
+   */
+  private readonly loadSpecCache = new Map<string, DslLoadSpec>()
+
+  private started = false
+  private readonly disposeCallbacks: Array<() => Promise<void> | void> = []
+
+  constructor(setup: RuntimeSetup) {
+    this.config = applyConfigDefaults(setup.config)
+    this.logger = setup.logger
+    this.log = setup.logger ?? new ConsoleLogger({ runtime: 'tbdlib' })
+
+    this.audit = new AuditEmitter({ mode: this.config.auditMode, log: this.log })
+    if (setup.audit !== undefined) {
+      const sinks = Array.isArray(setup.audit) ? setup.audit : [setup.audit]
+      for (const sink of sinks) this.audit.register(sink)
+    }
+
+    this.server = setup.server
+    this.data = setup.data
+    this.auth = setup.auth
+    this.queue = setup.queue
+    this.eventBus = setup.eventBus
+    this.scheduler = setup.scheduler
+    this.client = setup.client
+    this.storage = setup.storage
+    this.ai = setup.ai
+  }
+
+  /**
+   * Registra actions, reactions, schedules e/ou domínios. Aceita lista mista;
+   * distinção por shape via `isSchedule`/`isReaction`/`isDomainConfig`.
+   *
+   * Quando recebe um `DomainConfig`, achata via `flattenDomain` e registra
+   * as peças resultantes — qualquer colisão de nome (incluindo entre domínios
+   * registrados separadamente) é detectada aqui.
+   */
+  register(
+    items: Array<ActionDef | ReactionDef<any> | ScheduleDef | DomainConfig>,
+  ): void {
+    for (const item of items) {
+      if (isDomainConfig(item)) {
+        collectDomainWarnings(item)
+        const { actions, reactions, schedules } = flattenDomain(item)
+        this.registerFlat(actions, reactions, schedules)
+      } else if (isSchedule(item)) {
+        this.registerSchedules([item])
+      } else if (isReaction(item)) {
+        this.registerReactions([item])
+      } else {
+        this.registerActions([item as ActionDef])
+      }
+    }
+  }
+
+  /**
+   * Registra resolvers de entidades pra DSL `loads`.
+   *
+   * Quando uma action declara `loads: 'ticket(:id)'`, o runtime parsa o
+   * spec, resolve os args contra o input (`{ id: input.id }`) e chama o
+   * resolver registrado pra `ticket`.
+   *
+   * Closures em `action.loads` ignoram esse map — só specs string usam.
+   *
+   * Reregistrar a mesma entidade lança — fail-fast pra evitar shadow.
+   * Pra reset (testes), criar runtime novo.
+   */
+  registerLoaders(resolvers: Record<string, LoaderResolver>): void {
+    for (const [entity, resolver] of Object.entries(resolvers)) {
+      if (this.loaderResolvers.has(entity)) {
+        throw error({
+          code: 'runtime.duplicate_loader',
+          category: 'internal',
+          message: `Loader resolver "${entity}" already registered`,
+        })
+      }
+      this.loaderResolvers.set(entity, resolver)
+    }
+  }
+
+  private registerFlat(
+    actions: ActionDef[],
+    reactions: Array<ReactionDef<any>>,
+    schedules: ScheduleDef[],
+  ): void {
+    this.registerActions(actions)
+    this.registerReactions(reactions)
+    this.registerSchedules(schedules)
+  }
+
+  private registerActions(actions: ActionDef[]): void {
+    for (const action of actions) {
+      if (this.actions.has(action.name)) {
+        throw error({
+          code: 'runtime.duplicate_action',
+          category: 'internal',
+          message: `Action "${action.name}" registered twice`,
+        })
+      }
+      this.actions.set(action.name, action)
+    }
+  }
+
+  private registerReactions(reactions: Array<ReactionDef<any>>): void {
+    for (const reaction of reactions) {
+      if (this.reactions.has(reaction.name)) {
+        throw error({
+          code: 'runtime.duplicate_reaction',
+          category: 'internal',
+          message: `Reaction "${reaction.name}" registered twice`,
+        })
+      }
+      this.reactions.set(reaction.name, reaction)
+    }
+  }
+
+  private registerSchedules(schedules: ScheduleDef[]): void {
+    for (const schedule of schedules) {
+      if (this.schedules.has(schedule.name)) {
+        throw error({
+          code: 'runtime.duplicate_schedule',
+          category: 'internal',
+          message: `Schedule "${schedule.name}" registered twice`,
+        })
+      }
+      this.schedules.set(schedule.name, schedule)
+    }
+  }
+
+  /**
+   * Inicializa adapters, monta actions no server, subscreve reactions no event bus.
+   * Fail-fast: erro em qualquer init aborta o boot.
+   */
+  async start(): Promise<void> {
+    if (this.started) {
+      throw error({
+        code: 'runtime.already_started',
+        category: 'internal',
+        message: 'Runtime.start() called twice',
+      })
+    }
+
+    for (const adapter of this.allAdapters()) {
+      if (adapter.init !== undefined) await adapter.init(this)
+      if (adapter.dispose !== undefined) {
+        this.disposeCallbacks.push(adapter.dispose.bind(adapter))
+      }
+    }
+
+    if (this.server !== undefined) {
+      for (const action of this.actions.values()) this.server.mount(action)
+    }
+
+    if (this.eventBus !== undefined) {
+      for (const reaction of this.reactions.values()) this.subscribeReaction(reaction)
+    } else if (this.reactions.size > 0) {
+      throw error({
+        code: 'runtime.eventbus_required',
+        category: 'internal',
+        message: `${this.reactions.size} reaction(s) registered without an EventBusAdapter`,
+      })
+    }
+
+    if (this.scheduler !== undefined) {
+      for (const schedule of this.schedules.values()) this.registerSchedule(schedule)
+    } else if (this.schedules.size > 0) {
+      throw error({
+        code: 'runtime.scheduler_required',
+        category: 'internal',
+        message: `${this.schedules.size} schedule(s) registered without a SchedulerAdapter`,
+      })
+    }
+
+    this.started = true
+    this.log.info('runtime started', {
+      actions: this.actions.size,
+      reactions: this.reactions.size,
+      schedules: this.schedules.size,
+    })
+  }
+
+  /**
+   * Graceful shutdown. Chama `dispose()` em cada adapter registrado.
+   */
+  async dispose(): Promise<void> {
+    this.log.info('runtime disposing')
+    const callbacks = this.disposeCallbacks.slice().reverse()
+    for (const cb of callbacks) {
+      try {
+        await cb()
+      } catch (err) {
+        this.log.warn('adapter dispose failed', { error: String(err) })
+      }
+    }
+    this.started = false
+  }
+
+  /**
+   * Agrega `healthCheck()` de todos os adapters registrados. Adapter sem
+   * `healthCheck` é considerado ok.
+   */
+  async healthCheck(): Promise<{
+    ok: boolean
+    adapters: Record<string, HealthStatus>
+  }> {
+    const adapters: Record<string, HealthStatus> = {}
+    let ok = true
+
+    for (const adapter of this.allAdapters()) {
+      const key = `${adapter.kind}:${adapter.name}`
+      if (adapter.healthCheck === undefined) {
+        adapters[key] = { ok: true }
+        continue
+      }
+      try {
+        const status = await adapter.healthCheck()
+        adapters[key] = status
+        if (!status.ok) ok = false
+      } catch (err) {
+        adapters[key] = { ok: false, details: { error: String(err) } }
+        ok = false
+      }
+    }
+
+    const auditHealth = await this.audit.healthCheck()
+    adapters['audit:emitter'] = { ok: auditHealth.ok, details: auditHealth.details }
+    if (!auditHealth.ok) ok = false
+
+    return { ok, adapters }
+  }
+
+  /**
+   * Executa uma action de forma síncrona. Background actions usam
+   * `executeBackground` (não implementado em v0; queue adapter dispara).
+   */
+  async execute(
+    actionName: string,
+    input: unknown,
+    ctxBase: ContextBase,
+  ): Promise<ActionResult<unknown>> {
+    const action = this.actions.get(actionName)
+    if (action === undefined) {
+      return this.errorResult(actionName, error({
+        code: 'runtime.action_not_found',
+        category: 'not_found',
+        message: `Action "${actionName}" is not registered`,
+      }), 0, ctxBase.requestId)
+    }
+
+    const startedAt = performance.now()
+    const actionId = generateId()
+    const ctx = this.buildActionContext(action, actionId, ctxBase)
+
+    try {
+      // — 1. Validate input ————————————————————————————————————————————————
+      const validatedInput = await this.validate(action.input, input, 'input')
+
+      // — 2. Load —————————————————————————————————————————————————————————
+      const loaded = await this.runLoaders(action, ctx, validatedInput)
+
+      // — 3. Authenticate (public-or-user) ——————————————————————————————————
+      if (action.public !== true && ctx.user === null) {
+        throw error({
+          code: 'auth.unauthenticated',
+          category: 'authentication',
+          message: 'Authentication required',
+        })
+      }
+
+      // — 4. Authorize ——————————————————————————————————————————————————————
+      if (action.authorize !== undefined) {
+        const authorizeFn = this.compileAuthorize(action.authorize)
+        const decision = await authorizeFn(ctx, validatedInput, loaded)
+        if (decision === false) {
+          throw error({
+            code: 'auth.forbidden',
+            category: 'authorization',
+            message: 'Forbidden',
+          })
+        }
+        if (decision !== true) throw decision
+      }
+
+      // — 5. Handler ————————————————————————————————————————————————————————
+      // Modo design (`OPUS_MODE=design`): tenta mockHandler primeiro, cai
+      // no handler real se não houver. Em qualquer outro modo, handler real
+      // sempre manda. Leitura de env mora aqui, no boundary do execute — o
+      // resto do core continua sem tocar `process.env`.
+      const isDesignMode = isOpusDesignMode()
+      const handlerToRun =
+        isDesignMode && action.mockHandler !== undefined
+          ? action.mockHandler
+          : action.handler
+      const output = await handlerToRun(ctx, validatedInput, loaded)
+      const usedMock = handlerToRun === action.mockHandler
+
+      // — 6. Validate output (dev only) —————————————————————————————————————
+      // Search retorna Paginated<Item> mas `output` schema descreve só Item;
+      // skipamos pra evitar falso negativo. v1 pode validar items[].
+      const skipOutputValidation = action.kind === 'list'
+      const validatedOutput =
+        this.config.validateOutputInDev && !skipOutputValidation
+          ? await this.validate(action.output, output, 'output')
+          : output
+
+      // — 7. Audit ———————————————————————————————————————————————————————————
+      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: validatedOutput,
+          mode: usedMock ? 'design' : undefined,
+        }),
+        action.audit,
+      )
+
+      // — 8. Build result ———————————————————————————————————————————————————
+      return {
+        ok: true,
+        data: validatedOutput,
+        meta: this.buildMeta(actionId, action.name, durationMs, ctxBase.requestId),
+      }
+    } catch (thrown) {
+      const actionError = normalizeError(thrown)
+      const durationMs = performance.now() - startedAt
+      await this.audit.emit(
+        this.buildAuditRecord({
+          actionId,
+          action: action.name,
+          actionKind: action.kind,
+          outcome: 'error',
+          durationMs,
+          ctx,
+          input,
+          error: actionError,
+        }),
+        action.audit,
+      )
+      return {
+        ok: false,
+        error: actionError,
+        meta: this.buildMeta(actionId, action.name, durationMs, ctxBase.requestId),
+      }
+    }
+  }
+
+  // ===========================================================================
+  // Privados
+  // ===========================================================================
+
+  private *allAdapters(): IterableIterator<Adapter> {
+    if (this.logger !== undefined) yield this.logger
+    if (this.data !== undefined) yield this.data
+    if (this.auth !== undefined) yield this.auth
+    if (this.server !== undefined) yield this.server
+    if (this.queue !== undefined) yield this.queue
+    if (this.eventBus !== undefined) yield this.eventBus
+    if (this.scheduler !== undefined) yield this.scheduler
+    if (this.client !== undefined) yield this.client
+    if (this.storage !== undefined) yield this.storage
+    if (this.ai !== undefined) yield this.ai
+  }
+
+  /** As actions `ai:enabled` viradas em tool specs (cacheado — registry é estático pós-start).
+   *  Cada tool carrega o Schema do input; quem consome (driver, MCP server) converte pra
+   *  JSON Schema — o core não depende de zod-to-json-schema. Público: o bridge é reusado
+   *  pela cola do ctx.ai E pelo MCP server (`@softize/opus/mcp`). */
+  aiTools(): AiTool[] {
+    if (this.aiToolsCache !== null) return this.aiToolsCache
+    const tools: AiTool[] = []
+    for (const action of this.actions.values()) {
+      const cfg = normalizeAiConfig(action.ai)
+      if (cfg === null) continue
+      tools.push({
+        name: action.name,
+        description: cfg.description ?? action.description ?? action.name,
+        inputSchema: action.input,
+      })
+    }
+    this.aiToolsCache = tools
+    return tools
+  }
+
+  /** Liga o adapter de IA a um contexto: o `run` sai com as tools das actions `ai:enabled`
+   *  e o `execute` que roda a action COM ESTE contexto (auth de quem chamou) + o gate de
+   *  confirmação (destructive/requiresConfirmation). `complete`/`extract` passam direto.
+   *  Null se não há adapter. É a "cola" que mantém o driver puro (DI de tools+execute). */
+  private bindAi(base: ContextBase): BoundAi | null {
+    const adapter = this.ai
+    if (adapter === undefined) return null
+    const tools = this.aiTools()
+    // O execute-como-usuário + gate de confirmação é o mesmo nos dois modos (run/runStream).
+    const runOptions = (opts?: BoundAiRunOptions): AiRunOptions => ({
+      ...opts,
+      tools,
+      execute: async (name, toolInput) => {
+        const cfg = normalizeAiConfig(this.actions.get(name)?.ai)
+        if (cfg !== null && (cfg.destructive === true || cfg.requiresConfirmation === true)) {
+          const approved = opts?.confirm ? await opts.confirm({ name, input: toolInput }) : false
+          if (!approved) {
+            return { error: `A action "${name}" é destrutiva ou precisa de confirmação, e não foi aprovada.` }
+          }
+        }
+        const result = await this.execute(name, toolInput, base)
+        return result.ok ? result.data : { error: result.error }
+      },
+    })
+    return {
+      complete: (p, o) => adapter.complete(p, o),
+      extract: (p, s, o) => adapter.extract(p, s, o),
+      run: (input, opts) => {
+        if (adapter.run === undefined) {
+          throw new Error('O driver de IA configurado não implementa run (loop agêntico).')
+        }
+        return adapter.run(input, runOptions(opts))
+      },
+      runStream: (input, opts) => {
+        if (adapter.runStream === undefined) {
+          throw new Error('O driver de IA configurado não implementa runStream (loop agêntico em streaming).')
+        }
+        return adapter.runStream(input, runOptions(opts))
+      },
+    }
+  }
+
+  /** O adapter de IA LIGADO a um contexto — pra fora do handler (ex.: o backend do chat
+   *  resolve o usuário e chama `runtime.aiFor(base).run(historico)`). Null sem adapter. */
+  aiFor(base: ContextBase): BoundAi | null {
+    return this.bindAi(base)
+  }
+
+  private buildActionContext(
+    action: ActionDef,
+    actionId: string,
+    base: ContextBase,
+  ): ActionContext {
+    const dbExt = this.data?.contextExtension() ?? { db: undefined }
+    const provenance = resolveProvenance(base)
+    const log = this.log.child({
+      action: action.name,
+      actionId,
+      provenance: provenance.kind,
+      ...(base.tenantId !== null ? { tenant: base.tenantId } : {}),
+      ...(base.user !== null ? { userId: base.user.id } : {}),
+      ...(base.requestId !== undefined ? { requestId: base.requestId } : {}),
+    })
+
+    return {
+      user: base.user,
+      tenantId: base.tenantId,
+      can: base.can,
+      db: dbExt.db,
+      log,
+      emit: this.buildEmit(action, actionId, base),
+      storage: this.storage ?? null,
+      ai: this.bindAi(base),
+      provenance,
+      meta: base.meta ?? {},
+    }
+  }
+
+  private buildEmit(
+    action: ActionDef,
+    actionId: string,
+    base: ContextBase,
+  ): ActionContext['emit'] {
+    return async (event, data, meta) => {
+      if (
+        this.config.warnUndeclaredEmits &&
+        actionHasEmits(action) &&
+        !action.emits?.includes(event)
+      ) {
+        this.log.warn('handler emitted undeclared event', {
+          action: action.name,
+          event,
+          declared: action.emits,
+        })
+      }
+
+      if (this.eventBus === undefined) {
+        if (this.config.emitMode === 'strict') {
+          throw error({
+            code: 'emit.no_bus',
+            category: 'internal',
+            message: `ctx.emit('${event}') called without EventBusAdapter`,
+          })
+        }
+        this.log.warn('emit dropped — no EventBusAdapter', { event })
+        return
+      }
+
+      const domainEvent: DomainEvent = {
+        type: event,
+        id: generateId(),
+        timestamp: new Date().toISOString(),
+        actor: {
+          id: base.user?.id ?? null,
+          type: base.user !== null ? 'user' : 'system',
+        },
+        tenant: base.tenantId,
+        data,
+        source: {
+          action: action.name,
+          actionId,
+          ...(meta?.correlation !== undefined ? { correlation: meta.correlation } : {}),
+        },
+        ...(meta !== undefined ? { meta: meta as Record<string, unknown> } : {}),
+      }
+
+      try {
+        await this.eventBus.publish(domainEvent)
+      } catch (err) {
+        if (this.config.emitMode === 'strict') {
+          throw error({
+            code: 'emit.failed',
+            category: 'internal',
+            message: `failed to publish event "${event}"`,
+            cause: String(err),
+          })
+        }
+        this.log.warn('event publish failed (lenient)', {
+          event,
+          error: String(err),
+        })
+      }
+    }
+  }
+
+  private async validate<T>(
+    schema: Schema<T> | Schema<unknown, T>,
+    value: unknown,
+    kind: 'input' | 'output',
+  ): Promise<T> {
+    const result = await Promise.resolve(schema['~standard'].validate(value))
+    if ('value' in result) return result.value as T
+    throw error({
+      code: kind === 'input' ? 'validation.invalid_input' : 'validation.invalid_output',
+      category: kind === 'input' ? 'validation' : 'internal',
+      message: kind === 'input' ? 'Input validation failed' : 'Output validation failed (dev)',
+      issues: result.issues.map((iss) => ({
+        path: (iss.path ?? []).join('.'),
+        code: 'invalid',
+        message: iss.message,
+      })),
+    })
+  }
+
+  private async runLoaders(
+    action: ActionDef,
+    ctx: ActionContext,
+    input: unknown,
+  ): Promise<Record<string, unknown> | undefined> {
+    const spec = action.loads as LoadsSpec<unknown> | undefined
+    if (spec === undefined) return undefined
+
+    const entries = this.normalizeLoadsEntries(spec)
+    const loaded: Record<string, unknown> = {}
+    for (const [key, loader] of entries) {
+      const value = await this.runSingleLoader(action, ctx, input, loader)
+      if (value === null || value === undefined) {
+        throw error({
+          code: `${action.name}.${key}.not_found`,
+          category: 'not_found',
+          message: `Resource "${key}" not found for action "${action.name}"`,
+        })
+      }
+      loaded[key] = value
+    }
+    return loaded
+  }
+
+  /**
+   * Normaliza `LoadsSpec` em entries `[key, spec]`. Aceita:
+   *   - `Record<string, string | LoaderFn>` — key vira o key direto.
+   *   - `string[]` — extrai entidade de cada DSL e usa como key.
+   */
+  private normalizeLoadsEntries(
+    spec: LoadsSpec<unknown>,
+  ): Array<[string, string | LoaderFn<unknown>]> {
+    if (Array.isArray(spec)) {
+      return spec.map((dsl) => {
+        const parsed = this.parseLoadCached(dsl)
+        return [parsed.entity, dsl] as [string, string]
+      })
+    }
+    return Object.entries(spec) as Array<[string, string | LoaderFn<unknown>]>
+  }
+
+  private async runSingleLoader(
+    action: ActionDef,
+    ctx: ActionContext,
+    input: unknown,
+    loader: string | LoaderFn<unknown>,
+  ): Promise<unknown> {
+    if (typeof loader === 'string') {
+      const parsed = this.parseLoadCached(loader)
+      const resolver = this.loaderResolvers.get(parsed.entity)
+      if (resolver === undefined) {
+        throw error({
+          code: 'runtime.loader_not_registered',
+          category: 'internal',
+          message: `Load spec "${loader}" em action "${action.name}" referencia entidade "${parsed.entity}" sem resolver registrado — use runtime.registerLoaders({ ${parsed.entity}: ... })`,
+        })
+      }
+      const args = resolveLoadArgs(parsed, (input ?? {}) as Record<string, unknown>)
+      return await resolver(args, ctx)
+    }
+    // closure legacy: (ctx, input)
+    return await loader(ctx, input)
+  }
+
+  private parseLoadCached(src: string): DslLoadSpec {
+    const cached = this.loadSpecCache.get(src)
+    if (cached !== undefined) return cached
+    const parsed = parseLoad(src)
+    this.loadSpecCache.set(src, parsed)
+    return parsed
+  }
+
+  /**
+   * Compila `AuthorizeSpec` (string DSL ou closure) numa `AuthorizeFn`.
+   * String é parseada uma vez (cache por instância de runtime); a função
+   * resultante avalia a expressão contra um contexto plano com:
+   *   `{ user, input, ctx, ...loaded }`
+   * Resultado é coercido a boolean — DSL não retorna `ActionError`.
+   */
+  private compileAuthorize<In>(spec: AuthorizeSpec<In>): AuthorizeFn<In> {
+    if (typeof spec !== 'string') return spec
+    let ast = this.authorizeAstCache.get(spec)
+    if (ast === undefined) {
+      ast = parseExpression(spec)
+      this.authorizeAstCache.set(spec, ast)
+    }
+    const astCompiled = ast
+    return (ctx, input, loaded) => {
+      const evalCtx: Record<string, unknown> = {
+        user: ctx.user,
+        input,
+        ctx,
+        ...(loaded ?? {}),
+      }
+      return Boolean(evalExpression(astCompiled, evalCtx))
+    }
+  }
+
+  private buildAuditRecord(args: {
+    actionId: string
+    action: string
+    actionKind?: ActionDef['kind']
+    outcome: 'success' | 'error'
+    durationMs: number
+    ctx: ActionContext
+    input: unknown
+    output?: unknown
+    error?: ReturnType<typeof error>
+    /** Quando `'design'`, sinaliza que o mockHandler foi executado. */
+    mode?: 'design' | undefined
+  }): AuditRecord {
+    const record: AuditRecord = {
+      id: args.actionId,
+      timestamp: new Date().toISOString(),
+      action: args.action,
+      ...(args.actionKind !== undefined ? { actionKind: args.actionKind } : {}),
+      outcome: args.outcome,
+      durationMs: args.durationMs,
+      provenance: args.ctx.provenance,
+      actor: actorFromProvenance(args.ctx.provenance, args.ctx.user),
+      tenant: args.ctx.tenantId,
+      input: args.input,
+      severity: args.outcome === 'success' ? 'info' : severityForError(args.error),
+    }
+    if (args.output !== undefined) record.output = args.output
+    if (args.error !== undefined) record.error = args.error
+    if (args.mode !== undefined) record.meta = { mode: args.mode }
+    return record
+  }
+
+  private buildMeta(
+    actionId: string,
+    actionName: string,
+    durationMs: number,
+    requestId?: string,
+  ): ResultMeta {
+    const meta: ResultMeta = {
+      actionId,
+      action: actionName,
+      durationMs,
+    }
+    if (requestId !== undefined) meta.requestId = requestId
+    return meta
+  }
+
+  private errorResult(
+    actionName: string,
+    err: ReturnType<typeof error>,
+    durationMs: number,
+    requestId?: string,
+  ): ActionResult<never> {
+    return {
+      ok: false,
+      error: err,
+      meta: this.buildMeta(generateId(), actionName, durationMs, requestId),
+    }
+  }
+
+  private subscribeReaction(reaction: ReactionDef<any>): void {
+    if (this.eventBus?.subscribe === undefined) {
+      throw error({
+        code: 'runtime.subscribe_unsupported',
+        category: 'internal',
+        message: 'EventBusAdapter does not support subscribe()',
+      })
+    }
+    const patterns = Array.isArray(reaction.on) ? reaction.on : [reaction.on]
+    for (const pattern of patterns) {
+      const unsub = this.eventBus.subscribe(pattern, (event) => {
+        void this.runReaction(reaction, event)
+      })
+      this.disposeCallbacks.push(() => unsub())
+    }
+  }
+
+  private registerSchedule(schedule: ScheduleDef): void {
+    if (schedule.enabled === false) {
+      this.log.info('schedule disabled', { schedule: schedule.name })
+      return
+    }
+    // start() já validou que this.scheduler existe quando há schedules.
+    const scheduler = this.scheduler as SchedulerAdapter
+    const unsub = scheduler.register(schedule, async () => {
+      await this.fireSchedule(schedule)
+    })
+    this.disposeCallbacks.push(() => unsub())
+  }
+
+  private async fireSchedule(schedule: ScheduleDef): Promise<void> {
+    const input =
+      typeof schedule.input === 'function'
+        ? await (schedule.input as () => unknown | Promise<unknown>)()
+        : (schedule.input ?? {})
+    await this.execute(schedule.action, input, {
+      user: null,
+      tenantId: null,
+      can: () => false,
+      provenance: { kind: 'schedule', scheduleName: schedule.name },
+    })
+  }
+
+  private async runReaction(
+    reaction: ReactionDef<any>,
+    event: DomainEvent,
+  ): Promise<void> {
+    const provenance: Provenance = {
+      kind: 'reaction',
+      reactionName: reaction.name,
+      sourceActionId: event.source.actionId,
+      eventType: event.type,
+    }
+    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',
+      }),
+      emit: noopEmit,
+      storage: this.storage ?? null,
+      // Reação = contexto de sistema; o agente só alcança actions públicas (can nega por
+      // padrão — nada de LLM disparado por evento chamando action gated sem gate explícito).
+      ai: this.bindAi({
+        user: event.actor.id !== null ? ({ id: event.actor.id } as User) : null,
+        tenantId: event.tenant ?? null,
+        can: async () => false,
+        meta: {},
+      }),
+      provenance,
+      meta: {},
+    }
+
+    try {
+      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', {
+        code: actionError.code,
+        message: actionError.message,
+      })
+    }
+  }
+}
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+// ContextBase moveu pra types.ts (compartilhado entre core e adapters).
+
+/**
+ * Resolve provenance do ContextBase, com default `{ kind: 'system', source: 'unknown' }`
+ * quando caller não passa. Server adapter / scheduler / runtime devem sempre
+ * passar provenance explícita; default é safety net.
+ */
+function resolveProvenance(base: ContextBase): Provenance {
+  if (base.provenance !== undefined) return base.provenance
+  return { kind: 'system', source: 'unknown' }
+}
+
+/**
+ * Deriva o shape legado `actor: { id, type }` a partir de Provenance,
+ * preservando retrocompat de AuditRecord.
+ */
+function actorFromProvenance(
+  provenance: Provenance,
+  user: User | null,
+): AuditRecord['actor'] {
+  const base = ((): AuditRecord['actor'] => {
+    switch (provenance.kind) {
+      case 'http':
+        return user !== null
+          ? { id: user.id, type: 'user' }
+          : { id: null, type: 'user' }
+      case 'integration':
+        return { id: provenance.name, type: 'integration' }
+      case 'ai-agent':
+        return { id: provenance.agentId, type: 'integration' }
+      case 'schedule':
+      case 'reaction':
+      case 'background':
+      case 'self-observation':
+      case 'system':
+        return { id: user?.id ?? null, type: 'system' }
+    }
+  })()
+  const meta = userMeta(user)
+  return meta === undefined ? base : { ...base, meta }
+}
+
+/**
+ * name/email do user resolvido → `actor.meta` — o que todo sink re-resolvia
+ * (id→nome) por fora. Só os dois campos de identificação: o User é shape
+ * aberto e despejá-lo inteiro no log vazaria o que ninguém pediu.
+ */
+function userMeta(user: User | null): Record<string, unknown> | undefined {
+  if (user === null) return undefined
+  const meta: Record<string, unknown> = {}
+  if (typeof user['name'] === 'string') meta['name'] = user['name']
+  if (typeof user['email'] === 'string') meta['email'] = user['email']
+  return Object.keys(meta).length > 0 ? meta : undefined
+}
+
+function actionHasEmits(action: ActionDef): action is ActionDef & { emits: string[] } {
+  return (
+    (action.kind === 'simple' || action.kind === 'form') &&
+    Array.isArray((action as any).emits)
+  )
+}
+
+function severityForError(err: any): 'info' | 'warning' | 'error' {
+  /* v8 ignore next — defensivo; buildAuditRecord só chama com err presente */
+  if (err === undefined) return 'info'
+  if (err.severity === 'fatal') return 'error'
+  if (err.severity === 'warning') return 'warning'
+  return 'error'
+}
+
+/**
+ * Placeholder pra `ctx.emit` em reactions. Reaction chain (reaction emite
+ * eventos novos que disparam outras reactions) entra em v1+.
+ */
+const noopEmit: ActionContext['emit'] = async () => undefined
+
+function generateId(): string {
+  if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+    return crypto.randomUUID()
+  }
+  // fallback determinístico-suficiente quando crypto não disponível
+  return `id_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`
+}
+
+/**
+ * Único ponto do core que lê `process.env`. Usado pelo `execute()` pra
+ * decidir entre `handler` real e `mockHandler`. Isolado em função pra
+ * testabilidade — testes podem `vi.stubEnv('OPUS_MODE', ...)`.
+ *
+ * Mantém a invariante "core nunca lê env" intacta no resto do código:
+ * adapters/config seguem recebendo valores literais.
+ *
+ * Exportado (fora do index público) pro harness de `testing` aplicar a MESMA
+ * régua no `runAction` — a semântica de design mora num lugar só.
+ */
+export function isOpusDesignMode(): boolean {
+  // Acesso via globalThis: defensivo pra runtimes sem `process` (browser, edge) E
+  // não exige @types/node no consumidor que compila este source (apps web).
+  const g = globalThis as { process?: { env?: Record<string, string | undefined> } }
+  return g.process?.env?.['OPUS_MODE'] === 'design'
+}