@softize/opus 8.6.6

package/src/core/types.ts

@@ -0,0 +1,1356 @@
+/**
+ * tbdlib — Core types
+ *
+ * Tipos centrais do protocolo. Source of truth: `/docs/protocol.md`.
+ * Qualquer divergência entre este arquivo e a doc é bug; alinhar a doc primeiro,
+ * depois ajustar o código.
+ *
+ * Organização (numerada igual ao protocolo quando aplicável):
+ *   1. Primitivos & shared
+ *   2. Erro (§3)
+ *   3. Result (§6)
+ *   4. Contexto (§4)
+ *   5. Audit (§5)
+ *   6. Eventos (§11)
+ *   7. Jobs / background (§10)
+ *   8. Tipos lógicos (§7)
+ *   9. Specs (FieldSpec, FilterSpec, ConfirmSpec, ...) (§2)
+ *  10. Action — discriminated union (§2)
+ *  11. Reaction (§12)
+ *  12. Adapters (§8)
+ *  13. RuntimeConfig (§14)
+ */
+
+// =============================================================================
+// 1. Primitivos & shared
+// =============================================================================
+
+/**
+ * Referência i18n. Opt-in.
+ *   - `string` literal vira a si mesma (passthrough quando sem resolver).
+ *   - `{ key, default }` resolve via `RuntimeConfig.i18n.resolver`, com fallback no `default`.
+ * Ver §13.
+ */
+export type I18nRef = string | { key: string; default: string }
+
+/**
+ * Função pra cancelar uma inscrição (event bus, queue listener, etc).
+ */
+export type Unsubscribe = () => void
+
+/**
+ * Logger genérico que mora no contexto. Implementado por `LoggerAdapter`.
+ * Detalhes: §8.
+ */
+export interface Logger {
+  trace(msg: string, meta?: object): void
+  debug(msg: string, meta?: object): void
+  info(msg: string, meta?: object): void
+  warn(msg: string, meta?: object): void
+  error(msg: string, meta?: object): void
+  fatal(msg: string, meta?: object): void
+  /** Cria logger derivado com bindings pré-injetados (per-request, per-action). */
+  child(bindings: object): Logger
+}
+
+/**
+ * Path segment numa validation issue. Suporta tanto chave crua quanto wrapper.
+ * Espelha Standard Schema v1 spec.
+ */
+export interface SchemaPathSegment {
+  readonly key: PropertyKey
+}
+
+export interface SchemaIssue {
+  readonly message: string
+  readonly path?: ReadonlyArray<PropertyKey | SchemaPathSegment> | undefined
+}
+
+export interface SchemaResultSuccess<TOutput> {
+  readonly value: TOutput
+  readonly issues?: undefined
+}
+
+export interface SchemaResultFailure {
+  readonly issues: ReadonlyArray<SchemaIssue>
+}
+
+export type SchemaResult<TOutput> = SchemaResultSuccess<TOutput> | SchemaResultFailure
+
+/**
+ * Schema compatível com Standard Schema v1. Default vem de Zod (lib expõe `t.*`
+ * em `@softize/opus/core`), mas qualquer lib que implemente o spec funciona
+ * (Zod 3.24+, ArkType, Valibot via adapter).
+ *
+ * Mantemos o shape inline pra não acoplar core a `@standard-schema/spec`.
+ */
+export interface Schema<TInput = unknown, TOutput = TInput> {
+  readonly '~standard': {
+    readonly version: 1
+    readonly vendor: string
+    readonly validate: (
+      value: unknown,
+    ) => SchemaResult<TOutput> | Promise<SchemaResult<TOutput>>
+    readonly types?: { readonly input: TInput; readonly output: TOutput } | undefined
+  }
+}
+
+/** Helper pra extrair o tipo de output de um Schema. */
+export type InferOutput<S> = S extends Schema<unknown, infer Out> ? Out : never
+
+/** Helper pra extrair o tipo de input de um Schema. */
+export type InferInput<S> = S extends Schema<infer In, unknown> ? In : never
+
+// =============================================================================
+// 2. Erro (§3)
+// =============================================================================
+
+/**
+ * Categorias de erro com mapping HTTP default sugerido. Ver §3.
+ */
+export type ErrorCategory =
+  | 'validation'
+  | 'authentication'
+  | 'authorization'
+  | 'not_found'
+  | 'conflict'
+  | 'rate_limit'
+  | 'dependency'
+  | 'internal'
+
+export type Severity = 'warning' | 'error' | 'fatal'
+
+/**
+ * Issue dentro de `ActionError.issues` — usado tipicamente em erros de validation
+ * pra reportar múltiplos campos inválidos numa única resposta.
+ */
+export interface ValidationIssue {
+  path: string
+  code: string
+  message: string
+  i18nKey?: string
+  i18nParams?: Record<string, unknown>
+}
+
+/**
+ * Shape padronizado de erro emitido por qualquer action. Adapters de transporte
+ * serializam preservando estrutura. Ver §3.
+ */
+export interface ActionError {
+  code: string
+  category: ErrorCategory
+  message: string
+  severity: Severity
+  retriable: boolean
+  i18nKey?: string
+  i18nParams?: Record<string, unknown>
+  field?: string
+  issues?: ValidationIssue[]
+  cause?: unknown
+  meta?: Record<string, unknown>
+}
+
+/**
+ * Catálogo declarativo de erros que uma action pode emitir.
+ * Drive OpenAPI/AI tools — não é checado em runtime.
+ */
+export interface ErrorSpec {
+  code: string
+  category: ErrorCategory
+  description: string
+}
+
+// =============================================================================
+// 3. Result (§6)
+// =============================================================================
+
+export interface ResultMeta {
+  actionId: string
+  action: string
+  durationMs: number
+  requestId?: string
+  cached?: boolean
+}
+
+/**
+ * Envelope discriminated union retornado de toda execução síncrona.
+ * Background actions retornam `BackgroundResult<T>`.
+ */
+export type ActionResult<T> =
+  | { ok: true; data: T; meta: ResultMeta }
+  | { ok: false; error: ActionError; meta: ResultMeta }
+
+export type BackgroundResult<T> =
+  | { ok: true; data: JobHandle<T>; meta: ResultMeta }
+  | { ok: false; error: ActionError; meta: ResultMeta }
+
+/**
+ * Output de search actions: sempre paginado.
+ */
+export interface Paginated<T> {
+  items: T[]
+  cursor: { next: string | null; prev?: string | null }
+  total?: number
+}
+
+// =============================================================================
+// 4. Contexto (§4)
+// =============================================================================
+
+/**
+ * Origem (provenance) de uma execução. Identifica QUEM/O QUÊ disparou
+ * a action — humano, schedule, reaction, AI agent, integração externa.
+ *
+ * Discriminated union por `kind`. Provenance é populada pelo runtime ao
+ * receber a request/trigger; chega ao handler via `ctx.provenance` e
+ * é persistida no `AuditRecord.provenance`.
+ *
+ * Provenance chains: actions disparadas por `background` ou `reaction`
+ * preservam a `originalProvenance` permitindo rastrear a cadeia inteira
+ * até a origem humana/sistema.
+ */
+export type Provenance =
+  | { kind: 'http'; userId: string | null; requestId?: string }
+  | { kind: 'schedule'; scheduleName: string }
+  | {
+      kind: 'reaction'
+      reactionName: string
+      sourceActionId: string
+      eventType: string
+      originalProvenance?: Provenance
+    }
+  | {
+      kind: 'background'
+      queueName: string
+      jobId: string
+      originalProvenance?: Provenance
+    }
+  | { kind: 'ai-agent'; agentId: string; model?: string; sessionId?: string }
+  | { kind: 'integration'; name: string; payload?: Record<string, unknown> }
+  | { kind: 'self-observation'; monitorName: string }
+  | { kind: 'system'; source: string }
+
+/**
+ * Representação opaca do usuário autenticado. Shape exato é decidido pelo
+ * `AuthAdapter`. Core não opina além do `id`.
+ */
+export interface User {
+  id: string
+  [key: string]: unknown
+}
+
+/**
+ * Função que checa permissão. Plugada pelo `AuthAdapter`.
+ * tbdlib não implementa RBAC/ABAC — apenas delega.
+ */
+export type CanFn = (permission: string, resource?: unknown) => boolean | Promise<boolean>
+
+/**
+ * Função que emite um `DomainEvent`. Disponível em `ActionContext.emit` e
+ * `ReactionContext.emit`. Plugada pelo `EventBusAdapter`.
+ */
+export type EmitFn = <T = unknown>(
+  event: string,
+  data: T,
+  meta?: { correlation?: string; [k: string]: unknown },
+) => Promise<void>
+
+/**
+ * Contexto entregue ao handler de action. Composto por adapters: auth fornece
+ * `user`/`tenantId`/`can`; data fornece `db`; logger fornece `log`; eventbus
+ * fornece `emit`; storage/ai fornecem `storage`/`ai` (null quando não configurados).
+ */
+export interface ActionContext {
+  user: User | null
+  tenantId: string | null
+  can: CanFn
+  db: unknown
+  log: Logger
+  emit: EmitFn
+  storage: StorageAdapter | null
+  ai: BoundAi | null
+  provenance: Provenance
+  meta: Record<string, unknown>
+}
+
+/**
+ * Contexto entregue ao handler de reaction. Mais enxuto que `ActionContext`
+ * (sem `input`/`loaded`). Ver §12.
+ */
+export interface ReactionContext {
+  user: User | null
+  tenantId: string | null
+  db: unknown
+  log: Logger
+  emit: EmitFn
+  storage: StorageAdapter | null
+  ai: BoundAi | null
+  provenance: Provenance
+  meta: Record<string, unknown>
+}
+
+// =============================================================================
+// 5. Audit (§5)
+// =============================================================================
+
+/**
+ * Registro emitido após execução de action (sucesso ou falha).
+ * Persistido pelos `AuditSink` configurados. Ver §5.
+ */
+export interface AuditRecord {
+  id: string
+  timestamp: string
+  action: string
+  /**
+   * O `kind` da action executada — sink que filtra leitura (list/view = ruído)
+   * decide pelo record, sem receber os DOMAINS por fora pra montar Set de nomes.
+   */
+  actionKind?: ActionDef['kind']
+  outcome: 'success' | 'error'
+  durationMs: number
+
+  /**
+   * Provenance estruturada — origem do trigger (humano, schedule, reaction,
+   * AI, etc). Permite rastreabilidade da cadeia de execução.
+   */
+  provenance: Provenance
+
+  /**
+   * Actor derivado de provenance, mantido pra retrocompat.
+   * Em provenance de tipo `http`/`ai-agent`/`integration`, `actor.id` é
+   * derivado; em system/schedule/reaction sem chain, `actor.id` é null.
+   * `meta` vem populado pelo runtime com `name`/`email` do user resolvido
+   * (quando presentes) — sink não precisa re-resolver id→nome.
+   */
+  actor: {
+    id: string | null
+    type?: 'user' | 'system' | 'integration'
+    meta?: Record<string, unknown>
+  }
+  tenant?: string | null
+
+  input: unknown
+  output?: unknown
+  error?: ActionError
+
+  severity: 'info' | 'warning' | 'error'
+  trace?: {
+    requestId?: string
+    parentActionId?: string
+  }
+  meta?: Record<string, unknown>
+}
+
+/**
+ * Configuração opcional de audit por action. Quando `audit: true` (default),
+ * captura tudo. Quando `audit: false`, desabilita. Quando objeto, customiza.
+ */
+export interface AuditConfig {
+  fields?: string[]
+  redact?: string[]
+  severity?: 'info' | 'warning' | 'error'
+  sink?: string
+  output?: boolean | { fields?: string[]; redact?: string[] }
+}
+
+// =============================================================================
+// 6. Eventos (§11)
+// =============================================================================
+
+/**
+ * Evento de domínio emitido pelo handler via `ctx.emit`. Shape preservado pelo
+ * `EventBusAdapter` ao publicar/distribuir.
+ */
+export interface DomainEvent<T = unknown> {
+  type: string
+  id: string
+  timestamp: string
+  actor: { id: string | null; type?: 'user' | 'system' | 'integration' }
+  tenant?: string | null
+  data: T
+  source: {
+    action: string
+    actionId: string
+    correlation?: string
+  }
+  meta?: Record<string, unknown>
+}
+
+// =============================================================================
+// 7. Jobs / background (§10)
+// =============================================================================
+
+export type JobStatus = 'queued' | 'running' | 'done' | 'failed' | 'cancelled'
+
+/**
+ * Handle retornado por background action. Cliente pola ou subscribe pra
+ * acompanhar status até `done`/`failed`.
+ */
+export interface JobHandle<T = unknown> {
+  jobId: string
+  action: string
+  status: JobStatus
+  progress?: { percent?: number; message?: string; data?: unknown }
+  data?: T
+  error?: ActionError
+  enqueuedAt: string
+  startedAt?: string
+  finishedAt?: string
+  attempts: number
+}
+
+/**
+ * Especificação enviada pra `QueueAdapter.enqueue`. Core constrói; adapter
+ * persiste e processa.
+ */
+export interface JobSpec {
+  jobId: string
+  action: string
+  input: unknown
+  ctx: {
+    userId: string | null
+    tenantId: string | null
+    requestId?: string
+  }
+  config: {
+    queue?: string
+    priority?: 'high' | 'normal' | 'low'
+    retry?: { attempts: number; backoff?: BackoffSpec }
+    timeout?: number
+  }
+}
+
+export type BackoffSpec =
+  | { kind: 'fixed'; delayMs: number }
+  | { kind: 'exponential'; initialMs: number; multiplier?: number; maxMs?: number }
+
+/**
+ * Config de execução em background, declarada na action.
+ * Apenas `simple`/`form` aceitam.
+ */
+export interface BackgroundConfig {
+  enabled: true
+  queue?: string
+  priority?: 'high' | 'normal' | 'low'
+  retry?: { attempts: number; backoff?: BackoffSpec }
+  timeout?: number
+  progress?: boolean
+}
+
+/**
+ * Reporter injetado como 4º argumento do handler quando `background.progress: true`.
+ */
+export interface ProgressReporter {
+  report(p: {
+    percent?: number
+    message?: string
+    data?: unknown
+  }): Promise<void> | void
+}
+
+// =============================================================================
+// 8. Tipos lógicos (§7) — metadata anexada
+// =============================================================================
+
+/**
+ * Metadata anexada por `t.*` constructors. Adapters consultam pra mapear tipo
+ * lógico → coluna DB / widget UI / validação extra.
+ */
+export interface LogicalTypeMeta {
+  logicalType: string
+  params?: Record<string, unknown>
+}
+
+// =============================================================================
+// 9. Specs (§2)
+// =============================================================================
+
+export interface ConfirmSpec {
+  title: I18nRef
+  message?: I18nRef
+  destructive?: boolean
+  confirmLabel?: I18nRef
+  cancelLabel?: I18nRef
+}
+
+export interface RateLimitSpec {
+  window: number
+  max: number
+  key?: (ctx: ActionContext, input: unknown) => string
+}
+
+export interface AIConfig {
+  enabled?: boolean
+  description?: string
+  destructive?: boolean
+  requiresConfirmation?: boolean
+}
+
+export interface Example {
+  name: string
+  description?: string
+  input: unknown
+  output?: unknown
+  error?: unknown
+}
+
+export interface ActionMessages {
+  success?: I18nRef
+  error?: I18nRef
+  confirmation?: I18nRef
+}
+
+/**
+ * Origem de opções pra um campo (select/radio/lookup/autocomplete).
+ * Discriminated union por `kind`.
+ */
+export type OptionsSpec =
+  | { kind: 'static'; items: Array<{ value: string; label: I18nRef }> }
+  | { kind: 'dictionary'; ref: string }
+  | { kind: 'lookup'; source: string; depends?: string[] }
+
+/**
+ * Descrição de campo em `FormAction.fields`. Drive UI rendering + AI tool
+ * description per-field.
+ */
+export interface FieldSpec {
+  label: I18nRef
+  placeholder?: I18nRef
+  hint?: I18nRef
+  /** Ajuda no hover/foco da label (ícone ⓘ + tooltip). `hint` = texto auxiliar SOB o campo;
+   *  `help` = explicação mais longa, escondida atrás do ícone na label. */
+  help?: I18nRef
+
+  default?: unknown
+  mask?: string
+
+  depends?: string[]
+  showWhen?: (input: Record<string, unknown>) => boolean
+  requireWhen?: (input: Record<string, unknown>) => boolean
+
+  group?: string
+  order?: number
+
+  widget?: string
+  options?: OptionsSpec
+
+  aiDescription?: string
+}
+
+export type FilterOp =
+  | 'eq'
+  | 'neq'
+  | 'gt'
+  | 'gte'
+  | 'lt'
+  | 'lte'
+  | 'in'
+  | 'nin'
+  | 'contains'
+  | 'startsWith'
+  | 'endsWith'
+  | 'between'
+  | 'null'
+  | 'notNull'
+
+/**
+ * Descrição de filtro em `ListAction.filters`. Mode `'server'` (default,
+ * filtra na query do DB) ou `'client'` (filtra no React adapter sobre
+ * `items` já carregados).
+ */
+export interface FilterSpec {
+  label: I18nRef
+  placeholder?: I18nRef
+
+  type: 'text' | 'select' | 'lookup' | 'date' | 'number'
+  multiple?: boolean
+  mode?: 'server' | 'client'
+  operators?: FilterOp[]
+  path?: string
+
+  /** Filtro AVANÇADO: sai da barra inline e vai pro modal "Filtros" (com contador de
+   *  ativos no botão). Os não-avançados rendem inline na toolbar da listagem. */
+  advanced?: boolean
+
+  section?: string
+  depends?: string[]
+
+  options?: OptionsSpec
+
+  aiDescription?: string
+}
+
+/**
+ * Coluna declarativa de uma `ListAction` — a UI (ActionList) deriva a tabela
+ * daqui; células custom entram POR CIMA na UI (prop `cells`, chave = key). É a base
+ * do futuro column picker (o usuário escolher colunas): a lista completa vive no
+ * contrato, `hidden` marca as que nascem fora.
+ */
+export interface ListColumnSpec {
+  /** Chave do item (`Out`) que a coluna mostra. */
+  key: string
+  label: I18nRef
+  /** Render padrão: 'text' (default) · 'number' (alinha à direita) · 'date' (Intl) ·
+   *  'badge' (chip com o valor; dict/cores via célula custom por enquanto). */
+  type?: 'text' | 'number' | 'date' | 'badge'
+  /** Header clicável (asc ↔ desc). Convenção: a UI escreve `sort: '<key>:<dir>'` no
+   *  input; o handler implementa o orderBy. */
+  sortable?: boolean
+  /** Coluna encolhe ao conteúdo (não expande). */
+  fit?: boolean
+  /** Nasce oculta (candidata ao column picker). */
+  hidden?: boolean
+  /** Formato quando `type: 'date'` (Intl.DateTimeFormatOptions). */
+  dateFormat?: Intl.DateTimeFormatOptions
+}
+
+export interface SortSpec {
+  field: string
+  dir: 'asc' | 'desc'
+}
+
+export interface PeriodSpec {
+  value: string
+  label: I18nRef
+  /** Preset inicial da listagem. Sem marcado, o PRIMEIRO da lista é o default —
+   *  período é recorte obrigatório do caso de uso (não existe "sem período"). */
+  default?: boolean
+}
+
+export interface ExpandSpec {
+  description?: string
+  default?: boolean
+}
+
+// =============================================================================
+// 10. Action — discriminated union (§2)
+// =============================================================================
+
+export type ActionKind = 'simple' | 'form' | 'list' | 'view'
+
+export type AuthorizeFn<In, Loaded = Record<string, unknown>> = (
+  ctx: ActionContext,
+  input: In,
+  loaded?: Loaded,
+) => boolean | ActionError | Promise<boolean | ActionError>
+
+/**
+ * Authorize aceita string DSL ou closure.
+ *
+ *   - **String DSL**: avaliada pelo runtime contra um contexto formado por
+ *     `{ user, input, ctx, ...loaded }`. Resultado coercido pra boolean.
+ *     Ex: `'user.kind == "employee" OR ticket.assigneeId == user.id'`.
+ *   - **Closure (`AuthorizeFn`)**: escape hatch pra lógica que a DSL não
+ *     cobre (acesso a serviços externos, side effects, etc).
+ */
+export type AuthorizeSpec<In, Loaded = Record<string, unknown>> =
+  | string
+  | AuthorizeFn<In, Loaded>
+
+export type HandlerFn<In, Out, Loaded = Record<string, unknown>> = (
+  ctx: ActionContext,
+  input: In,
+  loaded?: Loaded,
+  progress?: ProgressReporter,
+) => Out | Promise<Out>
+
+export type LoaderFn<In> = (ctx: ActionContext, input: In) => Promise<unknown>
+
+/**
+ * Resolver registrado via `Runtime.registerLoaders`. Mapeia entidade DSL
+ * (ex: `'ticket'`) → função que recebe args já resolvidos do input mais o
+ * `ActionContext` e retorna a entidade carregada (ou null/undefined → not_found).
+ */
+export type LoaderResolver = (
+  args: Record<string, unknown>,
+  ctx: ActionContext,
+) => Promise<unknown> | unknown
+
+/**
+ * Spec individual de load:
+ *
+ *   - **String DSL** (`'ticket(:id)'`): runtime parsa via `parseLoad`, resolve
+ *     args contra o input e delega ao `LoaderResolver` registrado pra entidade.
+ *   - **Closure (`LoaderFn`)**: escape hatch que recebe `(ctx, input)` direto.
+ */
+export type LoadSpec<In> = string | LoaderFn<In>
+
+/**
+ * Specs de loads de um action.
+ *
+ *   - **Record nomeado** (`{ ticket: 'ticket(:id)', meta: async () => ... }`):
+ *     chave = nome da propriedade em `loaded`; valor = string DSL ou closure.
+ *   - **Array de strings** (`['ticket(:id)', 'shipment(:shipmentId)']`): cada
+ *     string é parseada e a entidade vira a chave em `loaded` (ex: `loaded.ticket`).
+ */
+export type LoadsSpec<In> = Record<string, LoadSpec<In>> | string[]
+
+/**
+ * Forma legada: `Record<string, LoaderFn<In>>`. Alias mantido pra
+ * retrocompat — código existente que importa `LoadersSpec` continua valendo,
+ * mas `LoadsSpec` é o novo nome (e aceita também string DSL).
+ */
+export type LoadersSpec<In> = Record<string, LoaderFn<In>>
+
+/**
+ * Campos compartilhados por todos os kinds de action. Discriminator (`kind`)
+ * e campos kind-specific vivem nas variantes abaixo.
+ *
+ * Dois tipos de input, um schema:
+ *
+ *   - **`In`** — o lado do FIO (o que o cliente envia, pré-parse). É o tipo
+ *     que client/contracts/fields enxergam. Campo com `.default()` é opcional
+ *     aqui.
+ *   - **`ParsedIn`** — o lado PARSEADO (o output do schema de input, defaults
+ *     aplicados). O runtime SEMPRE valida antes de executar, então `handler`,
+ *     `mockHandler`, `authorize` e `loads` recebem `ParsedIn`.
+ *
+ * O default `ParsedIn = In` mantém retrocompat com anotações à mão de dois
+ * genéricos; `defineAction`/`defineContract` inferem os dois lados do schema.
+ */
+export interface ActionBase<In, Out, ParsedIn = In> {
+  // — Identidade —
+  name: string
+  kind: ActionKind
+
+  // — Documentação / Application Interface —
+  label?: I18nRef
+  title?: I18nRef
+  summary?: string
+  description?: string
+  icon?: string
+  color?: 'primary' | 'success' | 'warning' | 'danger' | 'neutral' | string
+  messages?: ActionMessages
+  tags?: string[]
+  examples?: Example[]
+  errors?: ErrorSpec[]
+
+  // — Contrato —
+  input: Schema<In, ParsedIn>
+  output: Schema<Out>
+
+  // — Autorização (fail-closed default) —
+  public?: boolean
+  requires?: string | string[]
+  authorize?: AuthorizeSpec<ParsedIn>
+  loads?: LoadsSpec<ParsedIn>
+
+  // — Execução —
+  handler: HandlerFn<ParsedIn, Out>
+
+  /**
+   * Handler alternativo executado quando `process.env.OPUS_MODE === 'design'`.
+   * Use pra prototipar UI com dados realistas sem precisar do backend pronto.
+   *
+   * Em modo design: runtime tenta `mockHandler` primeiro; se ausente, cai
+   * no `handler` normal (permitindo testar pontualmente real ao lado de
+   * mocks).
+   *
+   * Em modo default (sem env): `mockHandler` é ignorado. Útil pra apagar
+   * em revisão ou manter pro Designer reusar.
+   *
+   * Pattern recomendado pra ações que só têm mock durante dev:
+   *
+   * ```ts
+   * defineAction({
+   *   name: 'ticket.list',
+   *   // ...
+   *   mockHandler: async () => MOCK_TICKETS,
+   *   handler: () => {
+   *     throw new Error('handler real ainda não implementado — use OPUS_MODE=design')
+   *   },
+   * })
+   * ```
+   */
+  mockHandler?: HandlerFn<ParsedIn, Out>
+
+  // — Comportamento —
+  audit?: boolean | AuditConfig
+  confirm?: ConfirmSpec
+  /** Avaliada no CLIENTE com o input do fio (pré-parse) — por isso `In`. */
+  invalidates?: string[] | ((input: In) => string[])
+  rateLimit?: RateLimitSpec
+  /** Server-side (pós-validação) — recebe o parseado. */
+  idempotency?: (input: ParsedIn) => string
+
+  // — Integração —
+  ai?: boolean | AIConfig
+  automatable?: boolean
+  internal?: boolean
+  successStatus?: number
+}
+
+export interface SimpleAction<In, Out, ParsedIn = In> extends ActionBase<In, Out, ParsedIn> {
+  kind: 'simple'
+  background?: BackgroundConfig
+  emits?: string[]
+}
+
+export interface FormAction<In extends Record<string, unknown>, Out, ParsedIn = In>
+  extends ActionBase<In, Out, ParsedIn> {
+  kind: 'form'
+  // Parcial: `fields` descreve as chaves RENDERÁVEIS do input — nem toda chave precisa
+  // de UI (ex.: `id` num update, ou campos derivados no servidor). O que não está aqui
+  // não é renderizado (mas segue no input, via defaultValues/submit).
+  fields: Partial<Record<keyof In & string, FieldSpec>>
+  background?: BackgroundConfig
+  emits?: string[]
+}
+
+export interface SearchFilters {
+  /** Colunas declarativas da listagem (a UI deriva a tabela; ver ListColumnSpec). */
+  columns?: ListColumnSpec[]
+  filters?: Record<string, FilterSpec>
+  sort?: { fields: string[]; default?: SortSpec[] }
+  paginate?: 'cursor' | 'offset' | false
+  text?: { fields: string[]; placeholder?: I18nRef }
+  periods?: PeriodSpec[]
+  /**
+   * Cláusula DSL aplicada **sempre** pelo repository do consumer (ex:
+   * `'NOT archived'`). Runtime NÃO executa SQL — quem consome a search
+   * compila via `compileWhere` do `@softize/opus/dsl` no momento de
+   * montar a query.
+   *
+   * Documentação que entra no manifest (próxima fase) e sinaliza intent
+   * de baseline imutável de filtragem.
+   */
+  where?: string
+}
+
+/**
+ * Em `ListAction`, `output` descreve o **item** (não o envelope).
+ * Handler retorna `Paginated<Out>`. Runtime não envelopa nem valida o
+ * envelope — handler é fonte de verdade.
+ */
+export interface ListAction<In, Out, ParsedIn = In>
+  extends Omit<ActionBase<In, Out, ParsedIn>, 'handler' | 'mockHandler'> {
+  kind: 'list'
+  handler: (
+    ctx: ActionContext,
+    input: ParsedIn,
+    loaded?: Record<string, unknown>,
+  ) => Paginated<Out> | Promise<Paginated<Out>>
+  /**
+   * Mesma semântica de `ActionBase.mockHandler`, mas devolve `Paginated<Out>`
+   * (search retorna lista paginada, não item solto).
+   */
+  mockHandler?: (
+    ctx: ActionContext,
+    input: ParsedIn,
+    loaded?: Record<string, unknown>,
+  ) => Paginated<Out> | Promise<Paginated<Out>>
+  /** Colunas declarativas da listagem (a UI deriva a tabela; ver ListColumnSpec). */
+  columns?: ListColumnSpec[]
+  filters?: Record<string, FilterSpec>
+  sort?: { fields: string[]; default?: SortSpec[] }
+  paginate?: 'cursor' | 'offset' | false
+  text?: { fields: string[]; placeholder?: I18nRef }
+  periods?: PeriodSpec[]
+  /**
+   * Ver `SearchFilters.where`. Baseline DSL aplicado pelo repository
+   * via `compileWhere` (do `@softize/opus/dsl`). Runtime não executa SQL.
+   */
+  where?: string
+}
+
+export interface ViewAction<In, Out, ParsedIn = In> extends ActionBase<In, Out, ParsedIn> {
+  kind: 'view'
+  /** Entidades relacionadas projetáveis. View simples não projeta nada — omita. */
+  projection?: string[]
+  expand?: Record<string, ExpandSpec>
+}
+
+/**
+ * Union completa de actions. Usada em runtime/adapters como "qualquer action";
+ * pra inferência precisa do subtipo, use o tipo concreto (SimpleAction, etc).
+ *
+ * `any` é proposital aqui — union de tipos genéricos com `unknown` quebra
+ * narrowing (porque `unknown` é supertipo, não subtipo). `defineAction` é
+ * generic e preserva o tipo exato passado.
+ */
+/* eslint-disable-next-line @typescript-eslint/no-explicit-any */
+export type ActionDef =
+  | SimpleAction<any, any>
+  | FormAction<any, any>
+  | ListAction<any, any>
+  | ViewAction<any, any>
+
+// =============================================================================
+// 11. Reaction (§12)
+// =============================================================================
+
+export type ReactionHandlerFn<Event = unknown> = (
+  ctx: ReactionContext,
+  event: DomainEvent<Event>,
+) => Promise<void> | void
+
+/**
+ * Declaração de listener de evento. Auto-registrada pelo `Runtime` no
+ * `EventBusAdapter` no `start()`. Ver §12.
+ */
+export interface ReactionDef<Event = unknown> {
+  name: string
+  on: string | string[]
+
+  description?: string
+  tags?: string[]
+
+  handler: ReactionHandlerFn<Event>
+
+  retry?: { attempts: number; backoff?: BackoffSpec }
+  timeout?: number
+  dedup?: (event: DomainEvent<Event>) => string
+  concurrency?: number
+
+  authorize?: (
+    ctx: ReactionContext,
+    event: DomainEvent<Event>,
+  ) => boolean | Promise<boolean>
+}
+
+// =============================================================================
+// 12. Adapters (§8)
+// =============================================================================
+
+export type AdapterKind =
+  | 'server'
+  | 'data'
+  | 'auth'
+  | 'audit'
+  | 'logger'
+  | 'queue'
+  | 'eventbus'
+  | 'scheduler'
+  | 'client'
+  | 'storage'
+  | 'ai'
+  | 'ui'
+  | 'schema'
+
+/**
+ * Resultado de health check de um adapter (ou do runtime agregado).
+ */
+export interface HealthStatus {
+  ok: boolean
+  details?: Record<string, unknown>
+}
+
+/**
+ * Interface base de adapter. Todos os adapters implementam `name`/`kind`;
+ * `init`/`dispose`/`healthCheck` são opcionais.
+ */
+export interface Adapter {
+  name: string
+  kind: AdapterKind
+  init?: (runtime: RuntimeRef) => Promise<void> | void
+  dispose?: () => Promise<void> | void
+  healthCheck?: () => Promise<HealthStatus>
+}
+
+/**
+ * Contexto mínimo que o caller (server adapter, etc) entrega ao runtime
+ * ao invocar uma action. Auth adapter resolveContext() produz isso.
+ */
+export interface ContextBase {
+  user: User | null
+  tenantId: string | null
+  can: CanFn
+  /**
+   * Provenance do trigger. Server adapter passa `{ kind: 'http', ... }`;
+   * schedule fires com `{ kind: 'schedule', ... }`; runtime preenche
+   * `{ kind: 'reaction', ... }` ao disparar reactions. Default
+   * `{ kind: 'system', source: 'unknown' }` se caller não passa.
+   */
+  provenance?: Provenance
+  meta?: Record<string, unknown>
+  requestId?: string
+}
+
+/**
+ * Referência ao runtime exposta pra adapters durante `init`.
+ * Adapters usam pra invocar actions e acessar auth/healthCheck.
+ *
+ * Mantemos as definições mínimas necessárias aqui (não a classe Runtime
+ * inteira) pra evitar dependência circular com `runtime.ts`.
+ */
+export interface RuntimeRef {
+  readonly config: RuntimeConfig
+  readonly log: Logger
+  readonly auth: AuthAdapter | undefined
+  execute(
+    actionName: string,
+    input: unknown,
+    ctx: ContextBase,
+  ): Promise<ActionResult<unknown>>
+  healthCheck(): Promise<{
+    ok: boolean
+    adapters: Record<string, HealthStatus>
+  }>
+}
+
+// — Endpoint specs (server adapter) ——————————————————————————————————————————
+
+export interface LogsEndpointSpec {
+  enabled: boolean
+  path?: string
+  auth: string | string[]
+  bufferSize?: number
+  source?: (query: LogQuery) => Promise<LogEntry[]>
+}
+
+export interface AuditEndpointSpec {
+  enabled: boolean
+  path?: string
+  auth: string | string[]
+  source?: (query: AuditQuery) => Promise<AuditRecord[]>
+}
+
+export interface EndpointSpec {
+  health?: boolean | { path?: string }
+  ready?: boolean | { path?: string }
+  openapi?: boolean | { path?: string; ui?: boolean }
+  actions?: boolean | { path?: string; auth?: string | string[] }
+  reactions?: boolean | { path?: string; auth?: string | string[] }
+  logs?: boolean | LogsEndpointSpec
+  audit?: boolean | AuditEndpointSpec
+}
+
+export interface LogQuery {
+  level?: 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal'
+  since?: string
+  until?: string
+  action?: string
+  tenant?: string
+  requestId?: string
+  userId?: string
+  limit?: number
+  cursor?: string
+}
+
+export interface LogEntry {
+  timestamp: string
+  level: 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal'
+  msg: string
+  meta?: Record<string, unknown>
+}
+
+export interface AuditQuery {
+  action?: string
+  actorId?: string
+  tenant?: string
+  outcome?: 'success' | 'error'
+  since?: string
+  until?: string
+  limit?: number
+  cursor?: string
+}
+
+// — Adapter interfaces específicas ————————————————————————————————————————————
+
+export interface ServerAdapter extends Adapter {
+  kind: 'server'
+  mount(action: ActionDef): void
+  mountEndpoints(spec: EndpointSpec): void
+}
+
+export interface DataAdapter extends Adapter {
+  kind: 'data'
+  contextExtension(): { db: unknown }
+}
+
+export interface AuthAdapter extends Adapter {
+  kind: 'auth'
+  resolveContext(req: unknown): Promise<{
+    user: User | null
+    tenantId?: string | null
+    can: CanFn
+  }>
+}
+
+export interface AuditSink extends Adapter {
+  kind: 'audit'
+  emit(record: AuditRecord): Promise<void> | void
+}
+
+export interface LoggerAdapter extends Adapter, Logger {
+  kind: 'logger'
+}
+
+export interface QueueAdapter extends Adapter {
+  kind: 'queue'
+  enqueue(spec: JobSpec): Promise<JobHandle>
+  status(jobId: string): Promise<JobHandle | null>
+  cancel(jobId: string): Promise<boolean>
+  subscribe?(jobId: string, listener: (h: JobHandle) => void): Unsubscribe
+}
+
+export interface EventBusAdapter extends Adapter {
+  kind: 'eventbus'
+  publish(event: DomainEvent): Promise<void> | void
+  subscribe?(
+    pattern: string,
+    listener: (event: DomainEvent) => void,
+  ): Unsubscribe
+}
+
+/** Opções do put de storage. `contentType` viaja pro driver (S3 grava; fs anota). */
+export interface StoragePutOptions {
+  contentType?: string
+}
+
+/** Objeto lido do storage: bytes + o contentType quando o driver o conhece. */
+export interface StorageObject {
+  data: Uint8Array
+  contentType?: string
+}
+
+/**
+ * EXPERIMENTAL — storage de objetos (arquivos): a superfície MÍNIMA que backoffice
+ * precisa (upload, download, remoção, URL de acesso). `key` é caminho lógico
+ * (`clientes/123/contrato.pdf`) — o driver resolve onde mora. Nasceu sem consumidor
+ * interno (jul/2026): a superfície cresce por reincidência, não por especulação
+ * (streams, list e metadata ricos entram quando um caso real os cobrar).
+ */
+export interface StorageAdapter extends Adapter {
+  kind: 'storage'
+  /** Grava (cria ou sobrescreve) o objeto. */
+  put(key: string, data: Uint8Array, opts?: StoragePutOptions): Promise<void>
+  /** Lê o objeto; null quando não existe. */
+  get(key: string): Promise<StorageObject | null>
+  /** Remove. Idempotente: remover o que não existe não é erro. */
+  delete(key: string): Promise<void>
+  /** URL de acesso (assinada/expirável no S3; `baseUrl` estática no fs). */
+  url(key: string, opts?: { expiresInSeconds?: number }): Promise<string>
+}
+
+/** Opções por chamada do `AiAdapter` — tudo tem default do driver. */
+export interface AiCompleteOptions {
+  /** System prompt da chamada. */
+  system?: string
+  /** Modelo (id do provider); default do driver. */
+  model?: string
+  /** Teto de tokens de saída; default do driver. */
+  maxTokens?: number
+  temperature?: number
+}
+
+/**
+ * EXPERIMENTAL — capability de IA generativa: a superfície MÍNIMA que backoffice
+ * precisa (completar texto e extrair dado estruturado). O diferencial do protocolo
+ * é o `extract`: o MESMO `Schema` das actions vira o contrato da resposta do modelo
+ * — o driver força saída estruturada e valida o retorno pelo schema antes de
+ * devolver. Chega nos handlers via `ctx.ai` (null quando não configurado).
+ * Superfície cresce por reincidência (streaming, chat multi-turn, tools livres
+ * entram quando um caso real os cobrar).
+ */
+export interface AiAdapter extends Adapter {
+  kind: 'ai'
+  /** Prompt de texto → resposta de texto. */
+  complete(prompt: string, opts?: AiCompleteOptions): Promise<string>
+  /** Prompt de texto → objeto VALIDADO pelo schema (saída estruturada). */
+  extract<T>(prompt: string, schema: Schema<T>, opts?: AiCompleteOptions): Promise<T>
+  /**
+   * Loop AGÊNTICO (tool-use multi-turn): o modelo escolhe uma tool → o `execute` injetado
+   * roda a action → o resultado volta pro modelo → repete até ele responder em texto (ou
+   * bater `maxSteps`). `tools` e `execute` vêm de FORA — o driver NÃO conhece o registry
+   * nem o runtime (DI); a cola que os monta a partir das actions `ai:enabled` mora no runtime.
+   * OPCIONAL: driver sem `run` só não oferece o loop (complete/extract seguem).
+   */
+  run?(input: string | AiMessage[], opts: AiRunOptions): Promise<AiRunResult>
+  /**
+   * Variante em STREAMING do `run` — mesmo loop, emitindo `ChatEvent` conforme acontece
+   * (tool em uso, texto incremental, fim). OPCIONAL e aditiva: driver sem `runStream`
+   * segue válido; quem consome decide o modo pelo que o driver oferece.
+   */
+  runStream?(input: string | AiMessage[], opts: AiRunOptions): AsyncIterable<ChatEvent>
+}
+
+/** Uma tool exposta ao modelo: nome da action + descrição + JSON Schema do input. */
+export interface AiTool {
+  name: string
+  description: string
+  inputSchema: unknown
+}
+
+/** Turno de conversa (histórico multi-turn do chat). */
+export interface AiMessage {
+  role: 'user' | 'assistant'
+  content: string
+}
+
+/** Uma opção de resposta de uma pergunta de esclarecimento (`ask_user`). */
+export interface AskOption {
+  label: string
+  description?: string
+}
+
+/** Uma pergunta que o agente faz À PESSOA no meio do turno, com opções. Espelha o
+ *  AskUserQuestion do Claude Code — mas servida por um round-trip REAL (ver `onAsk`), então
+ *  não volta vazia como o embutido faz em modo headless. */
+export interface AskQuestion {
+  question: string
+  header?: string
+  multiSelect?: boolean
+  options: AskOption[]
+}
+
+/** Resposta de UMA pergunta: os rótulos escolhidos + um texto livre opcional. */
+export interface AskAnswer {
+  header?: string
+  selected: string[]
+  text?: string
+}
+
+export interface AiRunOptions extends AiCompleteOptions {
+  /** Tools disponíveis (o runtime deriva das actions `ai:enabled`). */
+  tools: AiTool[]
+  /** Executa a tool escolhida (o runtime liga na action, com o contexto de quem chamou).
+   *  Devolve o resultado — ou um objeto de erro — que volta pro modelo. */
+  execute: (name: string, input: unknown) => Promise<unknown> | unknown
+  /** Teto de iterações do loop (default 8). */
+  maxSteps?: number
+  /** Round-trip de "perguntar à pessoa" (elicitação): se presente, o driver INTERCEPTA a tool
+   *  reservada `ask_user` (injetada automaticamente) e chama isto, devolvendo as respostas ao
+   *  modelo. AUSENTE = sem canal interativo: o driver RECUSA a `ask_user` com um erro acionável
+   *  (pergunte em texto e siga) em vez de deixar a chamada morrer no vazio — a pegadinha do
+   *  headless. Guarda QUALQUER consumidor por construção. */
+  onAsk?: (questions: AskQuestion[]) => Promise<AskAnswer[]> | AskAnswer[]
+}
+
+export interface AiRunResult {
+  /** Resposta final em texto. */
+  text: string
+  /** Iterações que o loop rodou. */
+  steps: number
+  /** Tools chamadas (observability). */
+  calls: Array<{ name: string; input: unknown }>
+}
+
+/**
+ * Evento de conversa — o protocolo que o loop agêntico em streaming emite e o `<Chat>`
+ * consome (docs/chat-event-protocol.md). O mínimo que os casos reais cobraram:
+ * texto incremental, tool em uso (dado cru; humanizar é apresentação), artefato
+ * produzido na conversa e fim de turno. O request/response clássico é o caso
+ * degenerado: `Promise<string>` ≡ um `text` + um `done`.
+ */
+export type ChatEvent =
+  | { type: 'text'; delta: string }
+  | { type: 'tool'; name: string; detail?: string }
+  | { type: 'artifact'; kind: string; ref: string; title?: string }
+  | { type: 'done'; ok: boolean; error?: string }
+
+/**
+ * Adapter de IA já LIGADO ao runtime — o que chega em `ctx.ai`. O `run` sai com as tools
+ * (actions `ai:enabled`) e o execute-como-usuário PRÉ-injetados; `complete`/`extract`
+ * passam direto pro driver.
+ */
+export interface BoundAi {
+  complete(prompt: string, opts?: AiCompleteOptions): Promise<string>
+  extract<T>(prompt: string, schema: Schema<T>, opts?: AiCompleteOptions): Promise<T>
+  run(input: string | AiMessage[], opts?: BoundAiRunOptions): Promise<AiRunResult>
+  /** Variante em streaming do `run` (mesmas tools/execute/confirm); exige driver com `runStream`. */
+  runStream(input: string | AiMessage[], opts?: BoundAiRunOptions): AsyncIterable<ChatEvent>
+}
+
+export interface BoundAiRunOptions extends AiCompleteOptions {
+  maxSteps?: number
+  /** Aprovação pras actions `destructive`/`requiresConfirmation`. Sem ela, essas actions
+   *  são RECUSADAS (o modelo avisa o usuário) — nada destrutivo sem o de-acordo. */
+  confirm?: (call: { name: string; input: unknown }) => boolean | Promise<boolean>
+  /** Elicitação: round-trip de perguntar à pessoa (ver `AiRunOptions.onAsk`). Passa direto
+   *  pro driver pelo spread de `runOptions` no bind. */
+  onAsk?: (questions: AskQuestion[]) => Promise<AskAnswer[]> | AskAnswer[]
+}
+
+/**
+ * Schedule declarativo. Tempo dispara o trigger; runtime executa a action
+ * referenciada com provenance `{ kind: 'schedule', scheduleName }`.
+ *
+ * Especifica timing via UM destes campos (exclusivo):
+ *   - `cron`: expressão cron padrão (5 ou 6 campos)
+ *   - `every`: intervalo simples ('1h', '30m', '15s', etc — ISO 8601 duration ou shorthand)
+ *
+ * Action referenciada deve existir no registry. Input dinâmico via função
+ * (chamada toda vez que schedule dispara) ou estático.
+ */
+export interface ScheduleDef {
+  name: string
+  action: string
+
+  /** Cron expression — ex: '0 9 * * *' (9am daily). */
+  cron?: string
+  /** Shorthand interval — ex: '1h', '30m', '15s'. */
+  every?: string
+  /** Timezone IANA — ex: 'America/Sao_Paulo'. Default: UTC. */
+  timezone?: string
+
+  /** Input passado ao runtime.execute(); estático ou dinâmico. */
+  input?: unknown | (() => unknown | Promise<unknown>)
+
+  /** Habilitação opt-in/out. Default true. */
+  enabled?: boolean
+
+  /** Documentação. */
+  description?: string
+  tags?: string[]
+}
+
+/**
+ * Adapter que materializa schedules — registra triggers temporais e chama
+ * o runtime quando o tempo bate.
+ *
+ * Drivers: `@softize/opus/scheduler/node-cron` (in-process), futuros: `/bullmq`
+ * (Redis-backed repeatable jobs), `/temporal`, etc.
+ */
+export interface SchedulerAdapter extends Adapter {
+  kind: 'scheduler'
+  /**
+   * Registra um schedule e retorna função pra cancelar. Chamado pelo
+   * runtime no `start()` pra cada schedule.
+   *
+   * Quando o tempo bater, o adapter chama `fire()` que internamente
+   * invoca runtime.execute() com provenance schedule.
+   */
+  register(spec: ScheduleDef, fire: () => Promise<void> | void): Unsubscribe
+}
+
+export interface ClientAdapter extends Adapter {
+  kind: 'client'
+  run<T>(action: ActionDef, input: unknown): Promise<ActionResult<T>>
+}
+
+// =============================================================================
+// 13. RuntimeConfig (§14)
+// =============================================================================
+
+/**
+ * Behavior knobs do runtime. Recebe valores literais — core nunca lê `process.env`.
+ * Defaults aplicados quando campo ausente. Ver §14.
+ */
+export interface RuntimeConfig {
+  // — Modos de falha —
+  auditMode?: 'lenient' | 'strict'
+  emitMode?: 'lenient' | 'strict'
+
+  // — Ambiente —
+  env?: 'development' | 'production' | 'test'
+  dev?: boolean
+
+  // — Validação —
+  validateOutputInDev?: boolean
+  warnUndeclaredEmits?: boolean
+
+  // — Resiliência —
+  dedupCacheTtl?: number
+  defaultRetry?: { attempts: number; backoff?: BackoffSpec }
+
+  // — i18n —
+  i18n?: {
+    resolver?: (ref: I18nRef, locale?: string) => string
+    defaultLocale?: string
+  }
+
+  // — Limites —
+  maxConcurrentActions?: number
+  maxConcurrentReactions?: number
+}