@softize/opus 20.0.0 → 21.0.0

package/src/core/runtime.ts

@@ -28,6 +28,7 @@ import type { LoadSpec as DslLoadSpec } from '../dsl/loads.ts'
 import type {
   ActionContext,
   ActionDef,
+  ActionError,
   ActionResult,
   Adapter,
   AuditRecord,
@@ -136,6 +137,8 @@ export interface RuntimeSetupConfig {
   validateOutputInDev?: boolean
   warnUndeclaredEmits?: boolean
   dedupCacheTtl?: number
+  /** Chaves concluídas que o dedup guarda por reaction; acima disso, descarta a mais antiga. Padrão 10.000. */
+  dedupCacheMaxEntries?: number
   defaultRetry?: { attempts: number; backoff?: BackoffSpec }
   i18n?: {
     resolver?: (ref: I18nRef, locale?: string) => string
@@ -143,6 +146,8 @@ export interface RuntimeSetupConfig {
   }
   maxConcurrentActions?: number
   maxConcurrentReactions?: number
+  /** Saltos de reaction que uma cadeia de eventos pode dar. Padrão 5 (ADR 0027). */
+  maxReactionDepth?: number
 }
 
 /**
@@ -157,6 +162,7 @@ export interface ResolvedRuntimeConfig {
   validateOutputInDev: boolean
   warnUndeclaredEmits: boolean
   dedupCacheTtl: number
+  dedupCacheMaxEntries: number
   defaultRetry: { attempts: number; backoff?: BackoffSpec }
   i18n: {
     resolver?: (ref: I18nRef, locale?: string) => string
@@ -164,6 +170,7 @@ export interface ResolvedRuntimeConfig {
   }
   maxConcurrentActions: number
   maxConcurrentReactions: number
+  maxReactionDepth: number
 }
 
 // =============================================================================
@@ -235,6 +242,7 @@ function applyConfigDefaults(c: RuntimeSetupConfig = {}): ResolvedRuntimeConfig
     validateOutputInDev: c.validateOutputInDev ?? dev,
     warnUndeclaredEmits: c.warnUndeclaredEmits ?? dev,
     dedupCacheTtl: c.dedupCacheTtl ?? 60_000,
+    dedupCacheMaxEntries: c.dedupCacheMaxEntries ?? 10_000,
     defaultRetry: c.defaultRetry ?? {
       attempts: 3,
       backoff: { kind: 'exponential', initialMs: 1000 },
@@ -242,9 +250,44 @@ function applyConfigDefaults(c: RuntimeSetupConfig = {}): ResolvedRuntimeConfig
     i18n,
     maxConcurrentActions: c.maxConcurrentActions ?? Number.POSITIVE_INFINITY,
     maxConcurrentReactions: c.maxConcurrentReactions ?? 10,
+    maxReactionDepth: c.maxReactionDepth ?? 5,
   }
 }
 
+/**
+ * Os limites que o runtime aplica às reactions travariam ou desligariam a entrega com um valor
+ * fora do domínio (zero vagas, TTL negativo): falhar na criação é melhor que parar em silêncio.
+ */
+function assertReactionLimits(config: ResolvedRuntimeConfig): void {
+  const invalid: string[] = []
+  if (!isPositiveIntegerOrInfinity(config.maxConcurrentReactions)) {
+    invalid.push(`maxConcurrentReactions (${String(config.maxConcurrentReactions)}) precisa ser um inteiro positivo`)
+  }
+  if (!isPositiveInteger(config.maxReactionDepth)) {
+    invalid.push(`maxReactionDepth (${String(config.maxReactionDepth)}) precisa ser um inteiro positivo`)
+  }
+  if (!isPositiveInteger(config.dedupCacheMaxEntries)) {
+    invalid.push(`dedupCacheMaxEntries (${String(config.dedupCacheMaxEntries)}) precisa ser um inteiro positivo`)
+  }
+  if (!(Number.isFinite(config.dedupCacheTtl) && config.dedupCacheTtl >= 0)) {
+    invalid.push(`dedupCacheTtl (${String(config.dedupCacheTtl)}) precisa ser um número de milissegundos maior ou igual a zero`)
+  }
+  if (invalid.length === 0) return
+  throw error({
+    code: 'runtime.invalid_config',
+    category: 'internal',
+    message: `A configuração do runtime tem valores inválidos: ${invalid.join('; ')}.`,
+  })
+}
+
+function isPositiveInteger(value: number): boolean {
+  return Number.isInteger(value) && value >= 1
+}
+
+function isPositiveIntegerOrInfinity(value: number): boolean {
+  return value === Number.POSITIVE_INFINITY || isPositiveInteger(value)
+}
+
 // =============================================================================
 // Runtime
 // =============================================================================
@@ -294,11 +337,19 @@ export class Runtime {
    */
   private readonly loadSpecCache = new Map<string, DslLoadSpec>()
 
+  /** Vagas globais de reaction (`config.maxConcurrentReactions`) e as de cada reaction. */
+  private readonly reactionSlots: Semaphore
+  private readonly reactionSlotsByName = new Map<string, Semaphore>()
+  /** Chaves de dedup por reaction; só existe para reactions que declaram `dedup`. */
+  private readonly reactionDedup = new Map<string, DedupCache>()
+
   private started = false
   private readonly disposeCallbacks: Array<() => Promise<void> | void> = []
 
   constructor(setup: RuntimeSetup) {
     this.config = applyConfigDefaults(setup.config)
+    assertReactionLimits(this.config)
+    this.reactionSlots = new Semaphore(this.config.maxConcurrentReactions)
     this.logger = setup.logger
     this.observability = setup.observability
     this.log = setup.logger ?? new ConsoleLogger({ runtime: 'opus' })
@@ -451,7 +502,12 @@ export class Runtime {
           message: `Reaction "${reaction.name}" registrada duas vezes`,
         })
       }
+      assertReactionPolicy(reaction)
       this.reactions.set(reaction.name, reaction)
+      this.reactionSlotsByName.set(reaction.name, new Semaphore(reaction.concurrency ?? 1))
+      if (reaction.dedup !== undefined) {
+        this.reactionDedup.set(reaction.name, new DedupCache(this.config.dedupCacheMaxEntries))
+      }
     }
   }
 
@@ -485,7 +541,10 @@ export class Runtime {
     // conexão aberta para trás. Sem scheduler, a checagem não roda porque nenhum schedule
     // executaria: os adapters inicializam e o start falha depois, com
     // `runtime.eventbus_required` se também faltar event bus, senão `runtime.scheduler_required`.
-    if (this.scheduler !== undefined) this.assertScheduledActionsExist()
+    if (this.scheduler !== undefined) {
+      this.assertScheduledActionsExist()
+      this.assertScheduledActionsAcceptSystem()
+    }
 
     for (const adapter of this.allAdapters()) {
       if (adapter.init !== undefined) await adapter.init(this)
@@ -627,6 +686,10 @@ export class Runtime {
     }
 
     const trace = normalizeTraceContext(spec.ctx.trace)
+    // O envelope já é a fonte da identidade do job (o `userId` acima). Só a marca `system`, gravada
+    // no enfileiramento a partir de `isSystemActor`, transporta a identidade de sistema; a
+    // provenance vem do chamador de `execute()` e não serve para isso (ADR 0028).
+    const system = spec.ctx.userId === null && spec.ctx.system === true
     return this.executeAction(action, spec.input, {
       ...ctxBase,
       tenantId: spec.ctx.tenantId,
@@ -640,15 +703,20 @@ export class Runtime {
           ? { originalProvenance: spec.ctx.originalProvenance }
           : {}),
       },
-    }, 'job', progress)
+    }, 'job', progress, system)
   }
 
+  /**
+   * `system` só é verdadeiro quando o próprio runtime inicia a execução pelo sistema — o disparo
+   * de um schedule ou o job que ele enfileirou. `execute()` nunca o recebe de fora.
+   */
   private async executeAction(
     action: ActionDef,
     input: unknown,
     ctxBase: ContextBase,
     execution: 'request' | 'job',
     progress?: ProgressReporter,
+    system = false,
   ): Promise<ActionResult<unknown>> {
 
     const startedAt = performance.now()
@@ -664,22 +732,17 @@ export class Runtime {
       ctxBase.trace,
       async (trace) => {
         const ctx = this.buildActionContext(action, actionId, ctxBase, trace)
+        if (system && ctx.user === null) systemContexts.add(ctx)
 
         try {
       // — 1. Validate input ————————————————————————————————————————————————
       const validatedInput = await this.validate(action.input, input, 'input')
 
-      // — 2. Authenticate (public-or-user) ——————————————————————————————————
+      // — 2. Authenticate (public, user or opted-in system) ————————————————————
       // Antes dos loaders: eles consultam dados, e um chamador anônimo não pode nem disparar essas
       // consultas nem distinguir, pelo erro de um loader, se um registro existe. A autenticação
       // não depende de nada carregado; a autorização, sim, e por isso vem depois.
-      if (action.public !== true && ctx.user === null) {
-        throw error({
-          code: 'auth.unauthenticated',
-          category: 'authentication',
-          message: 'Autenticação necessária',
-        })
-      }
+      assertAuthenticated(action, ctx)
 
       // — 3. Load —————————————————————————————————————————————————————————
       const loaded = await this.runLoaders(action, ctx, validatedInput)
@@ -724,6 +787,7 @@ export class Runtime {
             ...(ctxBase.requestId !== undefined ? { requestId: ctxBase.requestId } : {}),
             ...(trace !== undefined ? { trace } : {}),
             originalProvenance: ctx.provenance,
+            ...(isSystemActor(ctx) ? { system: true as const } : {}),
           },
           config: {
             ...(background.queue !== undefined ? { queue: background.queue } : {}),
@@ -1000,7 +1064,7 @@ export class Runtime {
         return
       }
 
-      const domainEvent: DomainEvent = {
+      await this.publish({
         type: event,
         id: generateId(),
         timestamp: new Date().toISOString(),
@@ -1017,24 +1081,29 @@ export class Runtime {
         },
         ...(trace !== undefined ? { trace } : {}),
         ...(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: `Falha ao publicar o evento "${event}"`,
-            cause: String(err),
-          })
-        }
-        this.log.warn('event publish failed (lenient)', {
-          event,
-          error: String(err),
+  /** Publica no barramento; a falha segue `config.emitMode`, para actions e reactions. */
+  private async publish(domainEvent: DomainEvent): Promise<void> {
+    // Quem chama já tratou a ausência do barramento; reactions só rodam com ele.
+    const bus = this.eventBus as EventBusAdapter
+    try {
+      await bus.publish(domainEvent)
+    } catch (err) {
+      if (this.config.emitMode === 'strict') {
+        throw error({
+          code: 'emit.failed',
+          category: 'internal',
+          message: `Falha ao publicar o evento "${domainEvent.type}"`,
+          cause: String(err),
         })
       }
+      this.log.warn('event publish failed (lenient)', {
+        event: domainEvent.type,
+        error: String(err),
+      })
     }
   }
 
@@ -1264,6 +1333,38 @@ export class Runtime {
     })
   }
 
+  /**
+   * Um schedule ativo cuja action não aceita o sistema falharia em todo disparo com
+   * `auth.system_forbidden`. Como o `schedule_action_not_found`, o erro sai no boot, antes de
+   * inicializar os adapters (ADR 0028).
+   */
+  private assertScheduledActionsAcceptSystem(): void {
+    const refused = [...this.schedules.values()].filter((schedule) => {
+      if (schedule.enabled === false) return false
+      const action = this.actions.get(schedule.action)
+      return action !== undefined && action.public !== true && action.automatable !== true
+    })
+    if (refused.length === 0) return
+    const list = refused
+      .map((schedule) => `"${schedule.name}" → "${schedule.action}"`)
+      .join(', ')
+    throw error({
+      code: 'runtime.schedule_action_not_automatable',
+      category: 'internal',
+      message:
+        `O runtime não iniciou porque ${
+          refused.length === 1
+            ? 'um schedule aponta para uma action que não aceita execução pelo sistema'
+            : `${refused.length} schedules apontam para actions que não aceitam execução pelo sistema`
+        }: ${list}. Declare \`automatable: true\` no contrato da action para que schedules possam ` +
+        'executá-la (ela continua exigindo usuário nas demais chamadas); para manter o schedule sem ' +
+        'executar, declare `enabled: false`.',
+      meta: {
+        schedules: refused.map((schedule) => ({ schedule: schedule.name, action: schedule.action })),
+      },
+    })
+  }
+
   private registerSchedule(schedule: ScheduleDef): void {
     if (schedule.enabled === false) {
       this.log.info('schedule disabled', { schedule: schedule.name })
@@ -1282,20 +1383,24 @@ export class Runtime {
       typeof schedule.input === 'function'
         ? await (schedule.input as () => unknown | Promise<unknown>)()
         : (schedule.input ?? {})
-    const result = await this.execute(schedule.action, input, {
+    const base: ContextBase = {
       user: null,
       tenantId: null,
       can: () => false,
       provenance: { kind: 'schedule', scheduleName: schedule.name },
-    })
+    }
+    const action = this.actions.get(schedule.action)
+    // O start() recusa schedule ativo sem action; o fallback mantém o envelope de erro de sempre.
+    const result = action === undefined
+      ? await this.execute(schedule.action, input, base)
+      : await this.executeAction(action, input, base, 'request', undefined, true)
     if (result.ok) return
     // Ninguém espera o resultado de um disparo: sem este registro, a falha só existiria no
     // audit da action. Action inexistente não chega aqui, porque o start() recusa o schedule.
     this.log.error(
       `O schedule "${schedule.name}" não concluiu a action "${schedule.action}" (${result.error.code}). ` +
         'O agendamento continua ativo e o próximo disparo executa a action de novo. Confira a ' +
-        'mensagem e o audit da action; `auth.unauthenticated` indica que a action agendada precisa ' +
-        'declarar `public: true`.',
+        'mensagem e o audit da action.',
       {
         schedule: schedule.name,
         action: schedule.action,
@@ -1308,25 +1413,84 @@ export class Runtime {
   }
 
   /**
-   * `ctx.emit` de reaction não publica: encadear reactions por evento ainda não é suportado.
-   * Fora de produção, o descarte vira aviso para que o evento não pareça ter sido entregue.
+   * `ctx.emit` de reaction publica somente os eventos do `emits` da reaction e leva a causa na
+   * cadeia; a profundidade para em `config.maxReactionDepth` (ADR 0027).
    */
-  private buildReactionEmit(reaction: ReactionDef<any>, log: Logger): ReactionContext['emit'] {
-    return async (event) => {
-      if (!this.config.dev) return
-      log.warn(
-        `A reaction "${reaction.name}" chamou ctx.emit('${event}'), mas reactions não publicam ` +
-          'eventos: o evento foi descartado e nenhuma reaction ou integração o recebe. Para ' +
-          'anunciar esse fato, emita-o no handler da action que o produz e declare-o em `emits`.',
-        { code: 'runtime.reaction_emit_ignored', reaction: reaction.name, event },
-      )
+  private buildReactionEmit(
+    reaction: ReactionDef<any>,
+    source: DomainEvent,
+    log: Logger,
+    trace: TraceContext | undefined,
+  ): ReactionContext['emit'] {
+    const declared = reaction.emits ?? []
+    return async (type, data, meta) => {
+      if (!declared.includes(type)) {
+        if (!this.config.warnUndeclaredEmits) return
+        log.warn(
+          `A reaction "${reaction.name}" chamou ctx.emit('${type}'), mas esse evento não está no ` +
+            '`emits` da reaction: o evento foi descartado e nenhuma reaction ou integração o ' +
+            `recebe. Para publicá-lo, acrescente '${type}' ao \`emits\` do binding da reaction.`,
+          { code: 'runtime.reaction_emit_ignored', reaction: reaction.name, event: type, declared },
+        )
+        return
+      }
+
+      const depth = (source.cause?.depth ?? 0) + 1
+      const maxDepth = this.config.maxReactionDepth
+      if (depth > maxDepth) {
+        const message =
+          `A reaction "${reaction.name}" não publicou o evento "${type}" porque a cadeia de ` +
+          `reactions chegaria à profundidade ${depth}, acima do limite de ${maxDepth} ` +
+          '(`config.maxReactionDepth`). Isso costuma indicar um laço: reactions que publicam ' +
+          'eventos que voltam a acioná-las. Confira o `on` e o `emits` das reactions da cadeia; ' +
+          'se a cadeia é intencional, aumente o limite.'
+        log.error(message, {
+          code: 'runtime.reaction_chain_too_deep',
+          reaction: reaction.name,
+          event: type,
+          depth,
+          maxDepth,
+          sourceEvent: { id: source.id, type: source.type },
+          origin: source.source,
+        })
+        if (this.config.emitMode === 'strict') {
+          throw error({
+            code: 'runtime.reaction_chain_too_deep',
+            category: 'internal',
+            message,
+            meta: { depth, maxDepth },
+          })
+        }
+        return
+      }
+
+      await this.publish({
+        type,
+        id: generateId(),
+        timestamp: new Date().toISOString(),
+        actor: source.actor,
+        ...(source.tenant !== undefined ? { tenant: source.tenant } : {}),
+        data,
+        source: {
+          ...source.source,
+          ...(meta?.correlation !== undefined ? { correlation: meta.correlation } : {}),
+        },
+        cause: { reaction: reaction.name, eventId: source.id, eventType: source.type, depth },
+        ...(trace !== undefined ? { trace } : {}),
+        ...(meta !== undefined ? { meta: meta as Record<string, unknown> } : {}),
+      })
     }
   }
 
+  /**
+   * Entrega um evento a uma reaction: dedup → vagas → authorize → handler com timeout → retry →
+   * audit (ADR 0026). Nunca rejeita: a falha fica no log e no audit, longe de quem emitiu.
+   */
   private async runReaction(
     reaction: ReactionDef<any>,
     event: DomainEvent,
   ): Promise<void> {
+    const startedAt = performance.now()
     const provenance: Provenance = {
       kind: 'reaction',
       reactionName: reaction.name,
@@ -1338,29 +1502,155 @@ export class Runtime {
       eventType: event.type,
       provenance: 'reaction',
     })
+    const delivery: ReactionDelivery = { attempts: 0, authorized: true }
+
+    // — (a) dedup: a chave é reservada na chegada, antes da fila de vagas ——————————
+    const dedup = this.reactionDedup.get(reaction.name)
+    let dedupKey: string | undefined
+    if (dedup !== undefined) {
+      try {
+        dedupKey = String(reaction.dedup?.(event))
+      } catch (thrown) {
+        const failure = normalizeError(thrown)
+        this.logReactionFailure(reactionLog, failure, delivery)
+        try {
+          await this.auditReaction(reaction, event, provenance, delivery, startedAt, event.trace, failure)
+        } catch (auditError) {
+          // `runReaction` nunca rejeita: quem o chama é o listener do barramento, sem `await`.
+          const auditFailure = normalizeError(auditError)
+          reactionLog.error('reaction audit failed', {
+            code: auditFailure.code,
+            message: auditFailure.message,
+            ...(auditFailure.cause !== undefined ? { cause: auditFailure.cause } : {}),
+          })
+        }
+        return
+      }
+      if (!dedup.claim(dedupKey, Date.now())) {
+        reactionLog.debug(
+          `A reaction "${reaction.name}" descartou o evento "${event.id}": a chave de dedup ` +
+            `"${dedupKey}" já foi processada ou está em processamento.`,
+          {
+            code: 'runtime.reaction_duplicate_skipped',
+            reaction: reaction.name,
+            eventId: event.id,
+            key: dedupKey,
+          },
+        )
+        return
+      }
+    }
+
+    let failure: ActionError | undefined
     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,
+        {
+          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) => {
+          try {
+            await this.deliverReaction(reaction, event, provenance, reactionLog, trace, delivery)
+          } catch (thrown) {
+            // O audit fica dentro do span, com o trace da reaction; a rejeição segue para o span.
+            await this.auditReaction(reaction, event, provenance, delivery, startedAt, trace, normalizeError(thrown))
+            throw thrown
+          }
+          if (delivery.authorized) {
+            await this.auditReaction(reaction, event, provenance, delivery, startedAt, trace)
+          }
+        },
+      )
+    } catch (thrown) {
+      failure = normalizeError(thrown)
+      this.logReactionFailure(reactionLog, failure, delivery)
+    }
+
+    if (dedup !== undefined && dedupKey !== undefined) {
+      // Falha definitiva libera a chave: uma nova entrega do mesmo evento pode tentar de novo.
+      if (failure !== undefined) dedup.release(dedupKey)
+      else dedup.complete(dedupKey, Date.now(), this.config.dedupCacheTtl)
+    }
+  }
+
+  /** (b) vagas, (c) authorize, (d) handler com timeout e (f) retry, dentro do span da entrega. */
+  private async deliverReaction(
+    reaction: ReactionDef<any>,
+    event: DomainEvent,
+    provenance: Provenance,
+    log: Logger,
+    trace: TraceContext | undefined,
+    delivery: ReactionDelivery,
+  ): Promise<void> {
+    const maxAttempts = reaction.retry?.attempts ?? 1
+    for (let attempt = 1; ; attempt += 1) {
+      const controller = new AbortController()
+      const ctx = this.buildReactionContext(reaction, event, provenance, log, trace, controller.signal)
+      const release = await this.acquireReactionSlots(reaction)
+      let delayMs: number
+      try {
+        if (attempt === 1 && reaction.authorize !== undefined) {
+          const allowed = await reaction.authorize(ctx, event)
+          if (!allowed) {
+            delivery.authorized = false
+            return
+          }
+        }
+        delivery.attempts = attempt
+        await runWithTimeout(reaction, () => reaction.handler(ctx, event), controller)
+        return
+      } catch (thrown) {
+        // Falha do authorize não é repetida: nenhuma tentativa do handler começou.
+        if (delivery.attempts < attempt || attempt >= maxAttempts || !isRetriable(thrown)) throw thrown
+        delayMs = backoffDelay(reaction.retry?.backoff, attempt)
+        const failed = normalizeError(thrown)
+        log.warn(
+          `A reaction "${reaction.name}" falhou na tentativa ${attempt} de ${maxAttempts} ` +
+            `(${failed.code}); a próxima tentativa começa em ${delayMs} ms.`,
+          {
+            code: 'runtime.reaction_retry',
+            reaction: reaction.name,
+            eventId: event.id,
+            attempt,
+            attempts: maxAttempts,
+            delayMs,
+            error: failed.code,
+            ...(failed.cause !== undefined ? { cause: failed.cause } : {}),
+          },
+        )
+      } finally {
+        release()
+      }
+      // A espera entre tentativas não ocupa vaga.
+      if (delayMs > 0) await sleep(delayMs)
+    }
+  }
+
+  private buildReactionContext(
+    reaction: ReactionDef<any>,
+    event: DomainEvent,
+    provenance: Provenance,
+    log: Logger,
+    trace: TraceContext | undefined,
+    signal: AbortSignal,
+  ): ReactionContext {
+    const user = event.actor.id !== null ? ({ id: event.actor.id } as User) : null
+    return {
+      user,
       tenantId: event.tenant ?? null,
       db: this.data?.contextExtension().db,
-      log: reactionLog,
-      emit: this.buildReactionEmit(reaction, reactionLog),
+      log,
+      emit: this.buildReactionEmit(reaction, event, log, trace),
       storage: this.storage ?? null,
       cache: this.cache ?? 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,
+        user,
         tenantId: event.tenant ?? null,
         can: async () => false,
         meta: {},
@@ -1369,24 +1659,58 @@ export class Runtime {
       provenance,
       ...(trace !== undefined ? { trace } : {}),
       meta: {},
+      signal,
     }
+  }
 
-        if (reaction.authorize !== undefined) {
-          const allowed = await reaction.authorize(ctx, event)
-          if (!allowed) return
-        }
-        await reaction.handler(ctx, event)
-      },
-    )
-    } catch (err) {
-      const actionError = normalizeError(err)
-      reactionLog.error('reaction failed', {
-        code: actionError.code,
-        message: actionError.message,
-        // Erro não tratado tem microcopy fixa; o texto original está em `cause`.
-        ...(actionError.cause !== undefined ? { cause: actionError.cause } : {}),
-      })
+  /** Vaga da reaction primeiro, global depois: quem espera a própria vaga não segura a global. */
+  private async acquireReactionSlots(reaction: ReactionDef<any>): Promise<() => void> {
+    const own = this.reactionSlotsByName.get(reaction.name) as Semaphore
+    const releaseOwn = await own.acquire()
+    const releaseGlobal = await this.reactionSlots.acquire()
+    return () => {
+      releaseGlobal()
+      releaseOwn()
+    }
+  }
+
+  /** (e) Um registro por entrega, com a identidade do evento e sem o payload (ADR 0026). */
+  private async auditReaction(
+    reaction: ReactionDef<any>,
+    event: DomainEvent,
+    provenance: Provenance,
+    delivery: ReactionDelivery,
+    startedAt: number,
+    trace: TraceContext | undefined,
+    failure?: ActionError,
+  ): Promise<void> {
+    const user = event.actor.id !== null ? ({ id: event.actor.id } as User) : null
+    const record: AuditRecord = {
+      id: generateId(),
+      timestamp: new Date().toISOString(),
+      action: reaction.name,
+      outcome: failure === undefined ? 'success' : 'error',
+      durationMs: performance.now() - startedAt,
+      provenance,
+      actor: actorFromProvenance(provenance, user),
+      tenant: event.tenant ?? null,
+      input: { event: { id: event.id, type: event.type, source: event.source } },
+      severity: failure === undefined ? 'info' : severityForError(failure),
+      ...(trace !== undefined ? { traceContext: trace } : {}),
+      meta: { kind: 'reaction', attempts: delivery.attempts },
     }
+    if (failure !== undefined) record.error = failure
+    await this.audit.emit(record)
+  }
+
+  private logReactionFailure(log: Logger, failure: ActionError, delivery: ReactionDelivery): void {
+    log.error('reaction failed', {
+      code: failure.code,
+      message: failure.message,
+      attempts: delivery.attempts,
+      // Erro não tratado tem microcopy fixa; o texto original está em `cause`.
+      ...(failure.cause !== undefined ? { cause: failure.cause } : {}),
+    })
   }
 
   /** Observabilidade nunca repete nem substitui o resultado do callback. */
@@ -1437,6 +1761,210 @@ async function settledSuccessfully<T>(promise: Promise<T>): Promise<boolean> {
 
 // ContextBase moveu pra types.ts (compartilhado entre core e adapters).
 
+// =============================================================================
+// Identidade de sistema (ADR 0028)
+// =============================================================================
+
+/**
+ * Contextos que o próprio runtime criou para uma execução do sistema. Um conjunto interno, e não
+ * a provenance, decide `isSystemActor`: qualquer código servidor pode montar uma provenance
+ * `schedule`, mas só o runtime acrescenta um contexto aqui.
+ */
+const systemContexts = new WeakSet<object>()
+
+/**
+ * Diz se a action está executando como o sistema: disparada por um schedule, ou no job que ele
+ * enfileirou, sem usuário. Use no `authorize` de uma action `automatable` para aceitar o sistema
+ * de forma explícita: `authorize: (ctx) => isSystemActor(ctx) || ctx.can('caixa:fechar')`.
+ * Passe o próprio `ctx` recebido: uma cópia, como `{ ...ctx }`, não é reconhecida.
+ */
+export function isSystemActor(ctx: ActionContext): boolean {
+  return systemContexts.has(ctx)
+}
+
+/**
+ * Marca um contexto como execução do sistema. Exportado fora do index público, só para o harness
+ * de `testing` aplicar a mesma regra no `runAction`.
+ */
+export function markSystemActor(ctx: ActionContext): void {
+  if (ctx.user === null) systemContexts.add(ctx)
+}
+
+/**
+ * O gate de autenticação do `execute` e do harness: sem usuário, a action precisa ser pública ou,
+ * quando o sistema a executa, `automatable`. Exportado fora do index público pelo mesmo motivo.
+ */
+export function assertAuthenticated(
+  action: { public?: boolean; automatable?: boolean },
+  ctx: ActionContext,
+): void {
+  if (action.public === true || ctx.user !== null) return
+  if (!isSystemActor(ctx)) {
+    throw error({
+      code: 'auth.unauthenticated',
+      category: 'authentication',
+      message: 'Autenticação necessária',
+    })
+  }
+  if (action.automatable !== true) {
+    throw error({
+      code: 'auth.system_forbidden',
+      category: 'authorization',
+      message: 'Esta action não aceita execução pelo sistema',
+    })
+  }
+}
+
+// =============================================================================
+// Política de entrega das reactions (ADR 0026)
+// =============================================================================
+
+interface ReactionDelivery {
+  /** Tentativas do handler que começaram. */
+  attempts: number
+  /** Falso quando o `authorize` recusou o evento: nada a auditar. */
+  authorized: boolean
+}
+
+/** Vagas em ordem de chegada. Ao liberar, a vaga passa direto para o próximo da fila. */
+class Semaphore {
+  private active = 0
+  private readonly waiting: Array<() => void> = []
+
+  constructor(private readonly limit: number) {}
+
+  async acquire(): Promise<() => void> {
+    if (this.active < this.limit) {
+      this.active += 1
+    } else {
+      await new Promise<void>((resolve) => this.waiting.push(resolve))
+    }
+    let released = false
+    return () => {
+      if (released) return
+      released = true
+      const next = this.waiting.shift()
+      if (next !== undefined) next()
+      else this.active -= 1
+    }
+  }
+}
+
+/**
+ * Chaves de dedup de uma reaction: ocupadas da chegada até o fim da entrega e, depois de um
+ * sucesso, até o TTL vencer. Com TTL constante, a ordem de inserção é a ordem de expiração, e a
+ * limpeza para na primeira chave ainda válida. As chaves concluídas têm teto
+ * (`config.dedupCacheMaxEntries`): acima dele, a mais antiga sai antes do TTL, e um evento com essa
+ * chave volta a ser aceito. As chaves em andamento não entram no teto.
+ */
+class DedupCache {
+  private readonly inFlight = new Set<string>()
+  private readonly completed = new Map<string, number>()
+
+  constructor(private readonly maxEntries: number) {}
+
+  claim(key: string, now: number): boolean {
+    this.prune(now)
+    if (this.inFlight.has(key) || this.completed.has(key)) return false
+    this.inFlight.add(key)
+    return true
+  }
+
+  complete(key: string, now: number, ttl: number): void {
+    this.inFlight.delete(key)
+    if (ttl <= 0) return
+    this.completed.set(key, now + ttl)
+    while (this.completed.size > this.maxEntries) {
+      const oldest = this.completed.keys().next().value as string
+      this.completed.delete(oldest)
+    }
+  }
+
+  release(key: string): void {
+    this.inFlight.delete(key)
+  }
+
+  private prune(now: number): void {
+    for (const [key, expiresAt] of this.completed) {
+      if (expiresAt > now) return
+      this.completed.delete(key)
+    }
+  }
+}
+
+/**
+ * Valores fora do domínio travariam a reaction (zero vagas) ou a desligariam (zero tentativas):
+ * o registro falha com o nome da reaction e o campo.
+ */
+function assertReactionPolicy(reaction: ReactionDef<any>): void {
+  const invalid: string[] = []
+  if (reaction.concurrency !== undefined && !isPositiveInteger(reaction.concurrency)) {
+    invalid.push(`concurrency (${String(reaction.concurrency)}) precisa ser um inteiro positivo`)
+  }
+  if (reaction.timeout !== undefined && !(Number.isFinite(reaction.timeout) && reaction.timeout > 0)) {
+    invalid.push(`timeout (${String(reaction.timeout)}) precisa ser um número de milissegundos maior que zero`)
+  }
+  if (reaction.retry !== undefined && !isPositiveInteger(reaction.retry.attempts)) {
+    invalid.push(`retry.attempts (${String(reaction.retry.attempts)}) precisa ser um inteiro positivo`)
+  }
+  if (invalid.length === 0) return
+  throw error({
+    code: 'runtime.invalid_reaction_policy',
+    category: 'internal',
+    message: `A reaction "${reaction.name}" declara uma política de entrega inválida: ${invalid.join('; ')}.`,
+    meta: { reaction: reaction.name },
+  })
+}
+
+/** Um `ActionError` pode vetar a repetição; exceções comuns e timeout são repetidos. */
+function isRetriable(thrown: unknown): boolean {
+  return isActionError(thrown) ? thrown.retriable !== false : true
+}
+
+function backoffDelay(spec: BackoffSpec | undefined, failedAttempt: number): number {
+  if (spec === undefined) return 0
+  if (spec.kind === 'fixed') return spec.delayMs
+  const delay = spec.initialMs * (spec.multiplier ?? 2) ** (failedAttempt - 1)
+  return spec.maxMs !== undefined ? Math.min(delay, spec.maxMs) : delay
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+/**
+ * Corre o handler contra o `timeout` da reaction. Ao vencer, aborta o sinal do contexto e rejeita
+ * a tentativa; o handler que ignora o sinal continua em segundo plano, sem segurar a vaga.
+ */
+async function runWithTimeout(
+  reaction: ReactionDef<any>,
+  run: () => Promise<void> | void,
+  controller: AbortController,
+): Promise<void> {
+  const execution = Promise.resolve().then(run)
+  const timeoutMs = reaction.timeout
+  if (timeoutMs === undefined) return execution
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const expired = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => {
+      const timeout = error({
+        code: 'runtime.reaction_timeout',
+        category: 'internal',
+        retriable: true,
+        message: `A reaction "${reaction.name}" não concluiu em ${timeoutMs} ms`,
+        meta: { timeoutMs },
+      })
+      controller.abort(timeout)
+      reject(timeout)
+    }, timeoutMs)
+  })
+  try {
+    await Promise.race([execution, expired])
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
 /**
  * Resolve provenance do ContextBase, com default `{ kind: 'system', source: 'unknown' }`
  * quando caller não passa. Server adapter / scheduler / runtime devem sempre