@softize/opus 8.6.6

package/docs/protocol.md

@@ -0,0 +1,2053 @@
+---
+title: Protocolo
+order: 1
+---
+
+# Opus — Protocolo
+
+> **Status:** v0. Esta doc descreve o protocolo do Opus **como ele é** — o código o implementa. Divergência entre código e doc é bug de um dos dois (a corrigir num dos lados), não "evolução natural" sem revisão da doc.
+
+---
+
+## 1. Tese
+
+**O Opus é o protocolo de actions de ponta a ponta.** Você declara uma action uma vez — input, autorização, execução, audit, feedback — e a lib materializa em UI, client, server e log via adapters.
+
+**Não é framework.** Não dona ciclo de vida, não tem router próprio, não tem ORM, não tem queue. É o contrato comum que todas as camadas falam.
+
+**O que o Opus não substitui:**
+- Auth provider (Better Auth, Clerk, próprio) — opus **lê** o contexto autenticado, não autentica.
+- Queue / job runner — opus pode emitir trigger, não executa.
+- ORM / DB client — opus não toca dado direto.
+- Design system / UI framework — Opus expõe metadata da action, UI consome.
+- HTTP framework — Opus gera handler, o framework hospeda.
+
+---
+
+## 2. Action: definição
+
+Uma **action** é uma unidade declarativa que flui pelo **pipeline padrão do Opus**: validar input → carregar recursos → autorizar → executar → auditar → retornar. Toda action atravessa esse pipeline, **independente de mudar estado ou não**.
+
+O valor da lib não é "escrita declarada" — é **pipeline declarado**. O mesmo pipeline serve write (form, simple) e read estruturado (search, view).
+
+### Papéis (todos os kinds cumprem)
+
+1. **Declarar** contrato (input, output, efeitos esperados).
+2. **Autorizar** quem pode disparar e sob quais condições.
+3. **Executar** a operação.
+4. **Auditar** o que aconteceu (quem, quando, dados, resultado).
+5. **Propagar** consequências (invalidação de cache, emissão de evento).
+
+### Kinds (v0)
+
+Toda action tem um `kind` que determina o **shape do contrato** — quais campos extras são válidos, como o backend se comporta, como a UI materializa.
+
+| Kind     | Quando                                | Backend                                | Frontend default       |
+|----------|---------------------------------------|----------------------------------------|------------------------|
+| `simple` | Operação direta sem input estruturado | Executa handler, audit                 | Botão/trigger          |
+| `form`   | Coleta input do usuário               | Valida input, executa, audit           | Form com fields        |
+| `search` | Lista filtrada/paginada               | Constrói query, paginação, sort        | Interface de busca     |
+| `view`   | Detalhe/projeção de entidade          | Join, projection, audit de acesso      | Display read-only      |
+
+Kinds são **extensíveis** — projetos podem adicionar (`bulk`, `wizard`, `async`) registrando no adapter UI. v0 do core trava esses quatro como first-class.
+
+### Contrato base (comum a todos os kinds)
+
+```ts
+type ActionBase<In, Out> = {
+  // — Identidade —
+  name: string                          // único, namespaced ('deal.archive')
+  kind: 'simple' | 'form' | 'search' | 'view'
+
+  // — Documentação / Application Interface (flat, top-level) —
+  label?:       I18nRef                 // texto do botão/link
+  title?:       I18nRef                 // título de dialog
+  summary?:     string                  // ≤ 80 chars; OpenAPI summary, AI tool desc
+  description?: string                  // markdown
+  icon?:        string                  // nome do ícone (Tabler, Lucide, etc — adapter resolve)
+  color?:       'primary' | 'success' | 'warning' | 'danger' | 'neutral' | string
+  messages?:    {
+    success?:      I18nRef
+    error?:        I18nRef
+    confirmation?: I18nRef
+  }
+  tags?:        string[]                // ['deals', 'mutations']
+  examples?:    Example[]
+  errors?:      ErrorSpec[]             // catálogo de erros possíveis
+
+  // — Contrato —
+  input:  Schema<In>                    // StandardSchemaV1-compatible
+  output: Schema<Out>
+
+  // — Autorização (fail-closed default) —
+  public?:    boolean                   // default false
+  requires?:  string | string[]         // permissão declarativa (drive OpenAPI/docs)
+  authorize?: (ctx, input, loaded?) =>
+                boolean | ActionError | Promise<boolean | ActionError>
+  loads?:     Record<string, (ctx, input) => Promise<unknown>>
+
+  // — Execução —
+  handler: (ctx, input, loaded?) => Out | Promise<Out>
+
+  // — Comportamento —
+  audit?:        boolean | AuditConfig  // default true
+  confirm?:      ConfirmSpec
+  invalidates?:  string[] | ((input: In) => string[])
+  rateLimit?:    { window: number, max: number, key?: (ctx, input) => string }
+  idempotency?:  (input: In) => string
+
+  // — Integração —
+  ai?:             boolean | AIConfig   // default true (opt-out via false)
+  automatable?:    boolean              // sistema/cron/workflow pode disparar
+  internal?:       boolean              // só service-to-service; não expõe REST
+  successStatus?:  number               // HTTP code de sucesso (default 200)
+}
+
+// simple/form ganham extra:
+type SimpleAction<In, Out> = ActionBase<In, Out> & {
+  kind: 'simple'
+  background?: BackgroundConfig         // executa em worker
+  emits?:      string[]                 // eventos que handler pode emitir
+}
+
+type FormAction<In, Out> = ActionBase<In, Out> & {
+  kind: 'form'
+  fields:      Record<keyof In & string, FieldSpec>
+  background?: BackgroundConfig
+  emits?:      string[]
+}
+
+// search/view não suportam background/emits em v0:
+type ListAction<In, Out> = ActionBase<In, Paginated<Out>> & {
+  kind: 'list'
+  filters?:  Record<string, FilterSpec>
+  sort?:     { fields: string[], default?: SortSpec[] }
+  paginate?: 'cursor' | 'offset' | false
+  text?:     { fields: string[] }
+  periods?:  { value: string, label: I18nRef }[]
+}
+
+type ViewAction<In, Out> = ActionBase<In, Out> & {
+  kind: 'view'
+  projection: string[]
+  expand?:    Record<string, ExpandSpec>
+}
+```
+
+### Campos por kind (detalhe dos sub-tipos)
+
+**`simple`**
+- `background?: BackgroundConfig` — executa em worker (ver §11).
+- `emits?: string[]` — eventos que handler pode emitir (ver §12).
+
+**`form`**
+- `fields: Record<string, FieldSpec>` — descrição de cada campo de input.
+- `background?`, `emits?` — idem simple.
+
+```ts
+type FieldSpec = {
+  // Display
+  label:        I18nRef
+  placeholder?: I18nRef
+  hint?:        I18nRef
+  
+  // Behavior
+  default?:     unknown
+  mask?:        string                  // input mask (CPF, telefone, ...)
+  
+  // Conditional
+  depends?:     string[]                // re-eval quando esses campos mudam
+  showWhen?:    (input) => boolean
+  requireWhen?: (input) => boolean
+  
+  // Layout
+  group?:       string                  // seção visual
+  order?:       number
+  
+  // UI override
+  widget?:      string                  // 'text' | 'select' | 'date' | 'rich' | custom
+  
+  // Options (select/radio/lookup)
+  options?:     OptionsSpec
+  
+  // AI guidance
+  aiDescription?: string
+}
+
+type OptionsSpec =
+  | { kind: 'static',     items: { value: string, label: I18nRef }[] }
+  | { kind: 'dictionary', ref: string }                            // catálogo nomeado
+  | { kind: 'lookup',     source: string, depends?: string[] }     // async
+```
+
+**`search`**
+- `filters?: Record<string, FilterSpec>` — filtros disponíveis (chave é nome).
+- `sort?`, `paginate?`, `text?`, `periods?` — ver tipos abaixo.
+
+```ts
+type FilterSpec = {
+  // Display
+  label:        I18nRef
+  placeholder?: I18nRef
+  
+  // Behavior
+  type:         'text' | 'select' | 'lookup' | 'date' | 'number'
+  multiple?:    boolean
+  mode?:        'server' | 'client'     // default 'server'
+  operators?:   FilterOp[]
+  path?:        string                  // dot path quando nome ≠ campo (filter.name → contact.name)
+  
+  // Layout
+  section?:     string                  // agrupamento UI ("Dados", "Período")
+  depends?:     string[]                // outros filtros que precisam estar preenchidos
+  
+  // Options
+  options?:     OptionsSpec
+  
+  aiDescription?: string
+}
+
+type FilterOp = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte'
+              | 'in' | 'nin' | 'contains' | 'startsWith' | 'endsWith'
+              | 'between' | 'null' | 'notNull'
+```
+
+Output de search action é **sempre** `Paginated<Output>` (ver §6).
+
+**`view`**
+- `projection: string[]` — campos/relações sempre carregados (`['owner', 'company.address']`).
+- `expand?: Record<string, ExpandSpec>` — relações opt-in por request.
+
+### Exemplos por kind
+
+```ts
+// simple
+defineAction({
+  name: 'deal.archive',
+  kind: 'simple',
+  input:  z.object({ dealId: z.string() }),
+  output: z.object({ archivedAt: t.datetime() }),
+  authorize: (ctx, input) => ctx.can('deal:archive', input.dealId),
+  handler:   async (ctx, input) => { /* ... */ },
+})
+
+// form
+defineAction({
+  name: 'deal.create',
+  kind: 'form',
+  input:  z.object({ title: z.string(), amount: t.money() }),
+  output: dealSchema,
+  authorize: (ctx) => ctx.can('deal:create'),
+  handler:   async (ctx, input) => { /* ... */ },
+  fields: {
+    title:  { label: 'Título' },
+    amount: { label: 'Valor', currency: 'BRL' },
+  },
+})
+
+// search
+defineAction({
+  name: 'deal.search',
+  kind: 'list',
+  input:  searchInputSchema,
+  output: paginatedDealsSchema,
+  authorize: (ctx) => ctx.can('deal:read'),
+  handler:   async (ctx, input) => { /* ... */ },
+  filter:   { fields: ['title', 'status', 'amount'] },
+  sort:     { fields: ['createdAt', 'amount'], default: { createdAt: 'desc' } },
+  paginate: 'cursor',
+})
+
+// view
+defineAction({
+  name: 'deal.view',
+  kind: 'view',
+  input:  z.object({ dealId: z.string() }),
+  output: dealDetailSchema,
+  authorize: (ctx, input) => ctx.can('deal:read', input.dealId),
+  handler:   async (ctx, input) => { /* ... */ },
+  projection: ['owner', 'company', 'attachments'],
+})
+```
+
+### Discriminated union
+
+`ActionDef` é uma união discriminada indexada por `kind`:
+
+```ts
+type ActionDef =
+  | SimpleAction
+  | FormAction
+  | ListAction
+  | ViewAction
+```
+
+TS narrowing dá autocomplete dos campos certos no editor. Adapters em runtime narrowam via guards (`isFormAction(a)`, `isListAction(a)`, ...).
+
+### O que ainda **não** é action
+
+Action ≠ qualquer leitura. Action = operação **estruturada** que cumpre os 5 papéis pelo pipeline.
+
+Fica **fora** do core:
+- Query SQL custom, agregação ad-hoc, ETL — não passam pelo pipeline.
+- Endpoints HTTP arbitrários — transporte é adapter.
+- Handler isolado sem schema/auth — função normal, não action.
+
+Critério prático: se você não consegue declarar `input` schematizado, `authorize`, e dizer qual kind se aplica, não é action.
+
+### Decisões de API
+
+- **Schema via `StandardSchemaV1`.** Default Zod; ArkType/Valibot são swap trivial.
+- **`kind` é discriminator obrigatório.** Não tem default — explicit > implicit.
+- **Estilo híbrido fn × OO** — ver §9 "Estilo de código". `defineAction`, `error()`, `t.*` são factory functions; `Runtime`, `Adapter`, `AuditSink`, `ActionPipeline` são classes.
+
+### Split contrato ↔ handler (`defineContract` / `bindAction`)
+
+O `defineAction` junta contrato (declarativo) + handler (server-only) num objeto
+só — ótimo num app mono-runtime, mas impede o **frontend** de importar a action
+sem arrastar db/segredos. Pra apps com superfícies separadas (web + api), o Opus
+parte isso em dois:
+
+- **`defineContract`** (roda nos dois lados → mora no `shared`): identidade,
+  `input`/`output`, `fields`/`filters`/`projection`, docs (`label`/`messages`/
+  `confirm`), e a regra `authorize` **action-level**. É `ActionDef` **sem** os
+  campos de execução.
+- **`bindAction(contract, binding)`** (server-only → mora na `api`): amarra
+  `handler`, `loads`, `background`, `emits`, `idempotency`, e um `authorize`
+  **row-level** (com `loaded`) que **sobrescreve** o do contrato. Produz um
+  `ActionDef` normal — o runtime não distingue.
+
+```ts
+// shared/ — o app (importável por web E api)
+export const archiveClient = defineContract({
+  name: 'client.archive', kind: 'form',
+  input: z.object({ id: z.string(), reason: z.string() }),
+  output: clientRowSchema,
+  fields: { reason: { label: 'Motivo' } },
+  authorize: (ctx) => ctx.can('client:archive'),   // regra → web usa pra gating de UX
+})
+
+// api/ — casca: só o server-only
+export const archiveClientAction = bindAction(archiveClient, {
+  loads:   (ctx, i) => ctx.db...,
+  authorize: (ctx, i, { client }) => ctx.can('client:archive', client),  // override row-level
+  handler: (ctx, i, { client }) => ...,
+})
+
+// web/ — render + call do MESMO contrato
+useAction(archiveClient)   // tipos, fields, confirm, authorize(UX) — tudo do contrato
+```
+
+**Por quê:** front e back não são domínios diferentes — são superfícies forçadas
+pela web. O contrato é a app; api e web são cascas. Fail-closed preservado: o
+runtime checa o `ActionDef` **já bindado** (sem `authorize` em nenhum dos dois +
+sem `public` → negado). Para CRUD, o mesmo padrão já é feito pela entidade
+(`shared`) + `crudActions` (`api`); o `defineContract` generaliza pras actions
+com lógica própria. Ver `docs/data-layer.md`.
+
+---
+
+## 3. Contrato de erro
+
+Todo erro emitido por uma action — seja por schema rejection, autorização negada, regra de negócio, ou falha de dependência — segue o **mesmo shape**. Adapters consomem esse shape; UI renderiza baseado nele; audit registra.
+
+### Shape
+
+```ts
+type ActionError = {
+  code:     string;          // "deal.archive.alreadyArchived"
+  category: ErrorCategory;   // ver enum abaixo
+  message:  string;          // default em EN, humano
+  severity: 'warning' | 'error' | 'fatal';
+  retriable: boolean;        // hint pro client decidir retry
+
+  i18nKey?:    string;       // chave para tradução (resolver é externo)
+  i18nParams?: Record<string, unknown>;
+
+  field?:   string;          // path do campo, para erros single-field
+  issues?:  ValidationIssue[]; // múltiplos issues (typicamente validation)
+
+  cause?:   unknown;         // erro original encadeado
+  meta?:    Record<string, unknown>; // dados auxiliares opcionais
+}
+
+type ValidationIssue = {
+  path:    string;           // "items.0.qty"
+  code:    string;           // "required", "out_of_range", ...
+  message: string;
+  i18nKey?:    string;
+  i18nParams?: Record<string, unknown>;
+}
+```
+
+### Categorias
+
+| Categoria         | Quando                                    | Default HTTP | Retriable |
+|-------------------|-------------------------------------------|--------------|-----------|
+| `validation`      | Input falhou schema ou regra de negócio   | 400          | false     |
+| `authentication`  | Não autenticado                           | 401          | false     |
+| `authorization`   | Autenticado mas sem permissão             | 403          | false     |
+| `not_found`       | Recurso não existe                        | 404          | false     |
+| `conflict`        | Colisão de estado (versão, idempotência)  | 409          | false     |
+| `rate_limit`      | Throttled                                 | 429          | true      |
+| `dependency`      | Upstream falhou (DB, API externa)         | 502          | true      |
+| `internal`        | Bug — não-categorizável                   | 500          | false     |
+
+**Mapeamento HTTP é responsabilidade do adapter**, não do contrato. Tabela acima é o default sugerido para o adapter `@softize/opus/server-*`.
+
+### Códigos
+
+Strings namespaced. Convenção:
+- Erros de uma action: `<action.name>.<error>` — ex: `deal.archive.alreadyArchived`.
+- Erros transversais: `<dominio>.<error>` — ex: `auth.forbidden`, `validation.required`.
+
+Códigos são **estáveis** — mudar código é breaking change. Mensagem é livre.
+
+### Como emitir
+
+Dentro do handler:
+
+```ts
+import { error } from '@softize/opus/core'
+
+handler: async (ctx, input) => {
+  const deal = await ctx.db.deals.findById(input.dealId)
+  if (!deal) throw error({
+    code: 'deal.archive.notFound',
+    category: 'not_found',
+    message: `Deal ${input.dealId} not found`,
+    i18nKey: 'deal.error.notFound',
+    i18nParams: { id: input.dealId },
+  })
+  if (deal.archivedAt) throw error({
+    code: 'deal.archive.alreadyArchived',
+    category: 'conflict',
+    message: 'Deal already archived',
+    retriable: false,
+  })
+  // ...
+}
+```
+
+Erros não-categorizados (ex: `throw new Error(...)` cru, ou exceção do driver do DB) são **normalizados** pelo runtime para `{ category: 'internal', code: 'internal.unhandled', severity: 'error', retriable: false, cause: <original> }`.
+
+### Validation: caso especial
+
+Erros de schema (input que não satisfaz Zod/ArkType) são **automaticamente** transformados em um único `ActionError`:
+
+```ts
+{
+  code:     'validation.invalid_input',
+  category: 'validation',
+  message:  'Input validation failed',
+  severity: 'warning',
+  retriable: false,
+  issues: [
+    { path: 'dealId',   code: 'required',  message: 'dealId is required' },
+    { path: 'priority', code: 'out_of_range', message: 'priority must be 1..5' },
+  ],
+}
+```
+
+Handler não vê erro de validation — runtime rejeita antes do handler executar.
+
+### Propagação client ↔ server
+
+Shape do erro **não muda** no transporte. Server emite `ActionError`; adapter de transporte serializa (JSON-safe); client adapter recebe e devolve o mesmo objeto tipado. `cause` é serializado como string (mensagem original) para evitar vazar stack/internals.
+
+### Severidade
+
+- `warning` — usuário pode corrigir e tentar (validation, conflict simples).
+- `error` — falha esperada do fluxo (autorização, not_found).
+- `fatal` — algo está quebrado e exige atenção (internal, dependency irrecuperável).
+
+Adapter de audit registra todos; sink de alerta (Sentry, etc) é configurado para filtrar por severidade.
+
+### O que **não** entra no contrato de erro
+
+- Stack traces — adapter de log decide se inclui em dev/prod.
+- Localização (idioma resolvido) — `i18nKey` é entregue; tradução fica no consumer.
+- Sugestões de UI ("clique aqui para tentar novamente") — UI decide com base em `category` + `retriable`.
+
+---
+
+## 4. Contrato de autorização
+
+O Opus **não autentica** e **não implementa RBAC**. O contrato é: action declara quem pode executá-la; contexto fornece os meios de checar; runtime aplica o resultado.
+
+### Princípio: fail-closed por default
+
+Action **sem** `authorize` declarado é **negada**. Para abrir explicitamente, declara `public: true`.
+
+```ts
+// ✓ acessível por qualquer um, inclusive não-autenticado
+defineAction({ name: 'session.heartbeat', public: true, ... })
+
+// ✓ acessível pra quem passa pela função
+defineAction({ name: 'deal.archive', authorize: (ctx, input) => ..., ... })
+
+// ✗ negada — autorize esquecido
+defineAction({ name: 'deal.archive', ... })
+```
+
+Esquecer `authorize` é erro do dev. Default seguro é negar, não falhar aberto.
+
+### Contexto
+
+`ctx` é o canal que opus provê pra autorização. Shape mínimo:
+
+```ts
+type ActionContext = {
+  user:     User | null;                  // null se não autenticado
+  tenantId: string | null;                // multi-tenant opcional
+  can:      (permission: string, resource?: unknown) =>
+              boolean | Promise<boolean>;
+  db:       unknown;                      // injetado pelo DataAdapter
+  log:      LoggerAdapter;                // injetado pelo LoggerAdapter (default console)
+  emit:     EmitFn;                       // emite DomainEvent via EventBusAdapter
+  storage:  StorageAdapter | null;        // storage de arquivos (experimental; null sem adapter)
+  provenance: Provenance;                 // quem disparou (http/schedule/reaction/…)
+  meta:     Record<string, unknown>;      // adapter pode estender
+}
+```
+
+`ctx.can()` é **delegado**. O Opus não implementa — o adapter ou o consumer plugam o engine de permissões (RBAC, ABAC, custom). Action chama `ctx.can('deal:archive', deal)` e confia que o consumer respondeu corretamente.
+
+### Forma do `authorize`
+
+```ts
+authorize: (ctx, input, loaded?) =>
+  boolean | ActionError | Promise<boolean | ActionError>
+```
+
+- `true` — permitido.
+- `false` — negado com erro genérico (`{ code: 'auth.forbidden', category: 'authorization' }`).
+- `ActionError` — negado com motivo específico (útil quando o "por quê" importa).
+
+```ts
+authorize: async (ctx, input, loaded) => {
+  if (!ctx.user) return false                              // genérico
+  if (loaded.deal.locked) return error({                   // específico
+    code: 'deal.archive.locked',
+    category: 'authorization',
+    message: 'Locked deals cannot be archived',
+  })
+  return ctx.can('deal:archive', loaded.deal)              // delega
+}
+```
+
+### Row-level via `loads`
+
+Para checar permissão sobre **um recurso específico**, action declara `loads` — o runtime carrega antes do `authorize` rodar:
+
+```ts
+defineAction({
+  name: 'deal.archive',
+  input: z.object({ dealId: z.string() }),
+  loads: {
+    deal: (ctx, input) => ctx.db.deals.findById(input.dealId),
+  },
+  authorize: (ctx, input, loaded) =>
+    ctx.can('deal:archive', loaded.deal),
+  handler: async (ctx, input, loaded) => {
+    // loaded.deal já carregado e tipado
+  },
+})
+```
+
+Vantagens:
+- Sem refetch — handler reusa `loaded.deal`.
+- Autorização não-vaza-handler — checagem fora da regra de negócio.
+- `not_found` é detectado antes do authorize (loader retorna null → erro `not_found` automático antes de chamar `authorize`).
+
+Loader pode falhar:
+- Retornar `null` → runtime emite `not_found` com código `<action>.<resource>NotFound`.
+- Lançar erro → propaga normalizado (`internal` ou categoria que o loader marcou).
+
+### Quando NÃO usar `loads`
+
+- Action **cria** recurso (não tem o que carregar antes).
+- Autorização é **action-level pura** (qualquer usuário com a permissão X pode executar, independente do recurso).
+- O recurso só pode ser determinado após executar o handler.
+
+Nesses casos, `authorize` recebe `(ctx, input)` e checa só permissão + input.
+
+### Composição
+
+Não há decorators nem múltiplos `authorize`. Composição é **dentro da função** — é só código TS:
+
+```ts
+const isOwner = (ctx, deal) => deal.ownerId === ctx.user?.id
+const isAdmin = (ctx) => ctx.user?.role === 'admin'
+
+defineAction({
+  name: 'deal.archive',
+  loads: { deal: (ctx, i) => ctx.db.deals.findById(i.dealId) },
+  authorize: (ctx, input, loaded) =>
+    isOwner(ctx, loaded.deal) || isAdmin(ctx),
+})
+```
+
+Não vai ter `compose(authA, authB)` no core. Se sentir falta, é regra de negócio mascarada de framework.
+
+### Distinção: `authenticate` vs `authorize`
+
+O Opus **não autentica** — não valida token, não emite sessão. O adapter (server) recebe a request, valida o token via auth provider externo (Better Auth, Clerk, próprio), monta `ctx.user`, e entrega pro Opus. A partir daí, `authorize` decide.
+
+Se `ctx.user` é `null` e `public !== true`, runtime rejeita com `{ code: 'auth.unauthenticated', category: 'authentication' }` **antes** de chamar `authorize`.
+
+---
+
+## 5. Contrato de audit
+
+Toda action **audita por default**. Para desabilitar (raramente justificável), declara `audit: false`. Para customizar (redação, severidade, sink), declara `audit: { ... }`.
+
+> Audit é o **log de negócio** de mudanças de estado. Não confundir com logging de aplicação (debug, info) — esses ficam por conta do logger do projeto.
+
+### Shape do registro
+
+```ts
+type AuditRecord = {
+  id:        string;          // UUID, único por evento
+  timestamp: string;          // ISO 8601 UTC
+  action:    string;          // nome da action ("deal.archive")
+  outcome:   'success' | 'error';
+  durationMs: number;
+
+  actor: {                    // quem disparou
+    id:   string | null;      // null = sistema / não autenticado
+    type?: 'user' | 'system' | 'integration';
+    meta?: Record<string, unknown>;
+  };
+  tenant?: string | null;
+
+  input:  unknown;            // já redacted (ver §config)
+  output?: unknown;           // já redacted, presente apenas em success
+  error?:  ActionError;       // presente apenas em outcome=error
+
+  severity: 'info' | 'warning' | 'error';
+  trace?: {
+    requestId?: string;
+    parentActionId?: string;  // quando esta action é disparada por outra
+  };
+  meta?: Record<string, unknown>;
+}
+```
+
+### Config por action
+
+```ts
+defineAction({
+  audit: true,                  // default — captura tudo
+})
+
+defineAction({
+  audit: false,                 // desabilita (precisa justificar em PR)
+})
+
+defineAction({
+  audit: {
+    fields?:   string[];        // whitelist de campos do input
+    redact?:   string[];        // blacklist (paths como "payment.cardNumber")
+    severity?: 'info' | 'warning' | 'error';  // baseline (default 'info')
+    sink?:     string;          // nome do sink ("primary", "compliance")
+    output?:   boolean | { fields?, redact? };  // captura output (default true)
+  },
+})
+```
+
+Regras de captura de input:
+- `fields` definido → captura **só** esses campos.
+- `redact` definido → captura tudo **menos** esses paths.
+- Ambos → primeiro filtra por `fields`, depois aplica `redact`.
+- Nenhum → captura input inteiro (default).
+
+Paths usam dot-notation (`payment.cardNumber`, `items.0.qty`). Redação substitui valor por `'[REDACTED]'`.
+
+### Severidade
+
+Mapeada do outcome + erro:
+
+| Outcome   | Tipo de erro           | Severity default |
+|-----------|------------------------|------------------|
+| success   | —                      | `info`           |
+| error     | `validation`           | `warning`        |
+| error     | `authentication`       | `warning`        |
+| error     | `authorization`        | `warning`        |
+| error     | `not_found`            | `warning`        |
+| error     | `conflict`             | `warning`        |
+| error     | `rate_limit`           | `warning`        |
+| error     | `dependency`           | `error`          |
+| error     | `internal`             | `error`          |
+
+Action pode forçar severidade via `audit.severity`. Erro `fatal` (severidade do ActionError) sobrescreve para `error` independente do mapping.
+
+### Sinks
+
+O Opus **não** implementa sink. Adapter ou consumer registra implementações da interface:
+
+```ts
+interface AuditSink {
+  name: string;
+  emit(record: AuditRecord): Promise<void> | void;
+}
+```
+
+Sinks são registrados no setup do runtime:
+
+```ts
+import { registerAuditSink } from '@softize/opus/core'
+
+registerAuditSink({
+  name: 'primary',
+  emit: async (record) => {
+    await db.auditLog.insert(record)
+  },
+})
+```
+
+Múltiplos sinks são permitidos. Action sem `audit.sink` emite para todos os sinks registrados; com `audit.sink: 'compliance'` emite só pro sink nomeado.
+
+### Falha de sink
+
+Falha ao emitir audit **não** falha a action. Sink lançou → opus loga `{ code: 'audit.sink.failed', cause: <error> }` no logger configurado e continua. Persistência de audit é responsabilidade do sink (retry, fila, etc).
+
+> Exceção: se você precisa de "no audit, no action" (compliance estrita), seu sink deve ser síncrono e opus oferece config `auditMode: 'strict'` no runtime — nesse modo, falha de sink **aborta** a action com `{ code: 'audit.required', category: 'internal' }`. Default é `'lenient'`.
+
+### O que **não** é audit
+
+- Logs de debug do handler — usa logger do projeto.
+- Métricas (counter de execuções, latência percentile) — usa observabilidade do projeto.
+- Traces distribuídos — usa OpenTelemetry no adapter; opus só carrega `trace.requestId` se o adapter populou.
+- Replay de actions — audit não foi desenhado pra reexecução. Event sourcing é outro contrato.
+
+---
+
+## 6. Envelope de resposta
+
+Toda execução de action — sucesso ou erro — produz um **`ActionResult`** com shape uniforme. Adapters de transporte serializam esse envelope; client adapter desserializa preservando estrutura.
+
+### Shape
+
+Discriminated union baseado em `ok`:
+
+```ts
+type ActionResult<T> =
+  | { ok: true;  data: T;            meta: ResultMeta }
+  | { ok: false; error: ActionError; meta: ResultMeta }
+
+type ResultMeta = {
+  actionId:   string;          // execução única — bate com AuditRecord.id
+  action:     string;          // nome da action
+  durationMs: number;
+  requestId?: string;          // trace, populado pelo adapter se disponível
+  cached?:    boolean;         // resultado serviu do cache do client
+}
+```
+
+Por que discriminated union e não `{ data, error }` separados:
+- Força narrowing no TS — impossível ler `data` em path de erro.
+- Sem estado inconsistente (`data` e `error` simultaneamente populados).
+- Idiomático no ecossistema (Result-like).
+
+### Consumo
+
+Server adapter retorna `ActionResult<Output>` diretamente. Client adapter expõe o mesmo:
+
+```ts
+const r = await client.run(archiveDeal, { dealId: 'd_123' })
+if (r.ok) {
+  console.log(r.data.archivedAt)      // tipo Output, narrow correto
+} else {
+  console.error(r.error.code, r.error.message)
+}
+```
+
+`@softize/opus/react` envolve em hook idiomático:
+
+```ts
+const { data, error, isLoading, run } = useAction(archiveDeal)
+```
+
+`data` e `error` ficam mutuamente exclusivos via o mesmo discriminated union.
+
+### Listas e paginação
+
+Actions do kind `search` retornam **sempre** `Paginated<T>`. Demais kinds (`simple`, `form`, `view`) retornam um único output (não paginado).
+
+```ts
+type Paginated<T> = {
+  items: T[];
+  cursor: {
+    next: string | null;
+    prev?: string | null;
+  };
+  total?: number;            // opcional — nem todo backend calcula barato
+}
+```
+
+**Default cursor-based.** Cursor escala melhor que offset, evita deslocamento em listas mutáveis, e adapter de DB pode otimizar. Search action pode declarar `paginate: 'offset'` quando o caso exige (admin tables, exports) — runtime traduz cursor opaco em `{ offset, limit }`.
+
+> **Nota de escopo:** reads ad-hoc (query SQL custom, agregação) **não** são actions. Search/view cobrem leitura **estruturada** (com schema, autorização, audit); fora desse padrão, consumer usa o que preferir (Drizzle direto, server actions, etc).
+
+### Streaming / progresso
+
+Versão v0 do protocolo: actions são **request/response**. Sem streaming.
+
+Adapters podem implementar streaming (ex: `@softize/opus/server-hono` com SSE pra progresso de action longa), mas o **contrato** de uma action declara `output` único. Se sentir falta, espera virar dor real em mais de um projeto antes de promover.
+
+### Meta — o que entra e o que não
+
+**Entra:**
+- `actionId`, `action`, `durationMs` — sempre.
+- `requestId` — quando o adapter de transporte forneceu (correlacionamento).
+- `cached` — quando o client adapter serviu do cache.
+
+**Não entra:**
+- Stack traces — fica no log/audit, não no envelope.
+- Dados de debug arbitrários — adapter pode adicionar via extension, mas core ignora.
+- Métricas (counters, percentile) — outro canal (observabilidade).
+
+---
+
+## 7. Catálogo de tipos lógicos
+
+Action declara input/output via schema (Zod/etc). Mas muitos campos têm **semântica conhecida** — `email`, `phone`, `money`, `datetime`. Repetir as regras de validação, formatação e mapping em cada projeto é ruído.
+
+O Opus oferece um **catálogo de tipos lógicos** — constructors prontos que retornam schemas com metadata anexada. Adapters leem a metadata e adaptam:
+- **DB adapter** sabe mapear pra coluna correta (`datetime` → `timestamp`, `money` → `numeric + currency`).
+- **UI adapter** sabe renderizar default (`email` → input type=email, `phone` → mask).
+- **Validation** já vem embutida (formato, range, normalização).
+
+### Uso
+
+```ts
+import { z } from 'zod'
+import { t } from '@softize/opus/schema/zod'
+
+defineAction({
+  input: z.object({
+    email:    t.email(),
+    phone:    t.phone({ country: 'BR' }),
+    amount:   t.money({ currency: 'BRL' }),
+    paidAt:   t.datetime(),
+    notes:    t.markdown(),
+  }),
+})
+```
+
+`t.email()` retorna um schema compatível com `StandardSchemaV1` (Zod por padrão) com metadata `{ logicalType: 'email' }`. Schema bruto (`z.string()`) continua aceito — só perde o benefício de adaptação automática.
+
+### Tipos core (v0)
+
+| Tipo lógico  | TS type            | Wire (JSON)         | Notas                                          |
+|--------------|--------------------|--------------------|------------------------------------------------|
+| `string`     | `string`           | string             | identidade — quando nenhum tipo específico cabe |
+| `text`       | `string`           | string             | multiline, sem normalização                    |
+| `int`        | `number`           | number             | inteiro 32-bit; runtime rejeita float          |
+| `bigint`     | `bigint`           | string             | wire em string pra não perder precisão JSON    |
+| `decimal`    | `string`           | string             | precisão arbitrária; nunca float               |
+| `boolean`    | `boolean`          | boolean            |                                                |
+| `datetime`   | `string` (ISO)     | string             | ISO 8601 UTC; handler decide hidratar pra Date |
+| `date`       | `string` (ISO)     | string             | `YYYY-MM-DD`                                   |
+| `time`       | `string`           | string             | `HH:mm:ss`                                     |
+| `duration`   | `string` (ISO)     | string             | ISO 8601 duration (`PT1H`, `P2D`)              |
+| `timezone`   | `string`           | string             | IANA (`America/Sao_Paulo`)                     |
+| `email`      | `string`           | string             | normaliza lowercase, valida RFC                |
+| `phone`      | `string`           | string             | E.164 (`+5511999999999`); opção `country`      |
+| `url`        | `string`           | string             | valida protocolo http/https por padrão         |
+| `uuid`       | `string`           | string             | UUID v4 default                                |
+| `slug`       | `string`           | string             | `[a-z0-9-]`, normaliza dashes                  |
+| `money`      | `{ amount, currency }` | object         | `amount: decimal`, `currency: ISO 4217`        |
+| `currency`   | `string`           | string             | ISO 4217 (`BRL`, `USD`)                        |
+| `country`    | `string`           | string             | ISO 3166 alpha-2 (`BR`, `US`)                  |
+| `locale`     | `string`           | string             | BCP 47 (`pt-BR`, `en-US`)                      |
+| `markdown`   | `string`           | string             | semântica de texto markdown                    |
+| `html`       | `string`           | string             | semântica de HTML; sanitização é do adapter    |
+| `json`       | `unknown`          | object             | payload opaco; runtime não estrutura           |
+| `enum`       | `string`           | string             | constructor recebe lista (`t.enum(['a','b'])`) |
+| `array`      | `T[]`              | array              | wrapper (`t.array(t.email())`)                 |
+| `object`     | `{ ... }`          | object             | wrapper (`t.object({ a: t.int() })`)           |
+
+### Metadata anexada
+
+Cada tipo lógico anexa, no mínimo:
+
+```ts
+{
+  logicalType: string;        // 'email', 'money', etc
+  params?: Record<string, unknown>;  // ex: { country: 'BR' } para phone
+}
+```
+
+Adapters consultam essa metadata via API utilitária (`getLogicalType(schema)`).
+
+### Extensão
+
+Projetos podem registrar tipos lógicos próprios:
+
+```ts
+import { defineLogicalType } from '@softize/opus/core'
+
+const cpf = defineLogicalType('cpf', {
+  schema: () => z.string().regex(/^\d{11}$/),
+  meta:   { format: 'cpf' },
+})
+
+defineAction({
+  input: z.object({ taxId: cpf() }),
+})
+```
+
+Tipos custom não vêm com adapter automático — quem implementar precisa estender adapter de DB/UI também (ou aceitar fallback para `string`).
+
+### O que **não** vira tipo lógico no core
+
+- Tipos domain-specific de um projeto (`cpf`, `cnpj`, `placa`) — vivem no projeto, não na lib.
+- Tipos de moeda específicos (`brl`, `usd` separados) — usa `money` com `currency`.
+- Tipos compostos pesados (`address`, `geoPoint`) — projeto define como object com tipos core dentro.
+
+Critério: entra no core o que tem **representação universal** e benefício real de mapping cross-adapter. Resto vive no projeto.
+
+---
+
+## 8. Adapters
+
+Core do Opus é **abstrato** — não tem HTTP, não tem DB, não tem framework de UI. Adapters são **superfícies (subpaths) do pacote único `@softize/opus`** que **conectam o protocolo a uma stack concreta**. O Opus é distribuído como **um pacote, uma versão** (`@softize/opus`); cada categoria abaixo é um subpath ESM, não um pacote separado.
+
+### Tipos de adapter
+
+| Categoria | Superfície          | Drivers (subpath)                                  |
+|-----------|---------------------|----------------------------------------------------|
+| Server    | `@softize/opus/server`    | `/fastify`, `/hono`                                |
+| Data      | `@softize/opus/data`      | `/kysely`, `/drizzle`                              |
+| Auth      | `@softize/opus/auth`      | `/better-auth`, `/clerk`                           |
+| Audit     | `@softize/opus/audit`     | `/pg`, `/sentry`, `/console`                       |
+| Logger    | `@softize/opus/log`       | `/pino` (console fica no `core`)                   |
+| Queue     | `@softize/opus/queue`     | `/bullmq`, `/inngest`, `/redis`                    |
+| EventBus  | `@softize/opus/events`    | `/mitt` (default), `/redis`, `/nats`               |
+| Client    | `@softize/opus/client`    | `/fetch`, `/tanstack`                              |
+| UI        | `@softize/opus/ui`        | `/react`, `/vue` (futuro)                          |
+| Schema    | `@softize/opus/schema`    | `/zod` (default), `/arktype`, `/valibot` (futuro)  |
+
+**Convenção:** `@softize/opus/<kind>` é a superfície; `/<driver>` é o driver (subpath aninhado). Padrão estilo Drizzle (`drizzle-orm/pg-core`). Mantém regra única sem exceções (`@softize/opus/queue/redis` e `@softize/opus/events/redis` convivem sem ambiguidade).
+
+```bash
+# Instalação — um pacote só; os peers vêm conforme os drivers que você usa
+pnpm add @softize/opus fastify kysely
+
+# Uso
+import { fastifyServer } from '@softize/opus/server/fastify'
+import { kyselyData }    from '@softize/opus/data/kysely'
+```
+
+Drivers são opt-in via subpath: bundle inclui só o que você importar. Peer deps de cada driver (fastify, hono, kysely, drizzle, etc) são declaradas como `peerDependenciesMeta` optional.
+
+### Interface base
+
+Todo adapter implementa `Adapter`:
+
+```ts
+interface Adapter {
+  name:    string;
+  kind:    'server' | 'data' | 'auth' | 'audit' | 'logger'
+         | 'queue' | 'eventbus' | 'client' | 'ui' | 'schema';
+  init?:        (runtime: Runtime) => Promise<void> | void;
+  dispose?:     () => Promise<void> | void;
+  healthCheck?: () => Promise<{ ok: boolean, details?: object }>;
+}
+```
+
+Cada `kind` estende com contratos específicos:
+
+```ts
+interface ServerAdapter extends Adapter {
+  kind: 'server';
+  mount(action: ActionDef): void;       // expõe action no transporte
+  mountEndpoints(spec: EndpointSpec): void;  // /health, /ready, /logs, etc
+}
+
+type EndpointSpec = {
+  health?:   boolean | { path?: string }                  // default true
+  ready?:    boolean | { path?: string }                  // default true
+  openapi?:  boolean | { path?: string, ui?: boolean }    // default true
+  actions?:  boolean | { path?: string, auth?: string }   // default false
+  reactions?: boolean | { path?: string, auth?: string }  // default false
+  logs?:     boolean | LogsEndpointSpec                   // default false
+  audit?:    boolean | AuditEndpointSpec                  // default false
+}
+
+type LogsEndpointSpec = {
+  enabled:     boolean
+  path?:       string                                     // default '/logs'
+  auth:        string | string[]                          // permission required
+  bufferSize?: number                                     // ring buffer, default 1000
+  source?:     (query: LogQuery) => Promise<LogEntry[]>   // custom (Datadog, etc)
+}
+
+type AuditEndpointSpec = {
+  enabled:  boolean
+  path?:    string                                        // default '/audit'
+  auth:     string | string[]
+  source?:  (query: AuditQuery) => Promise<AuditRecord[]>
+}
+
+interface DataAdapter extends Adapter {
+  kind: 'data';
+  contextExtension(): { db: unknown };  // entra no ctx
+}
+
+interface AuthAdapter extends Adapter {
+  kind: 'auth';
+  resolveContext(req: unknown): Promise<{
+    user: User | null;
+    tenantId?: string | null;
+    can: (perm: string, resource?: unknown) => boolean | Promise<boolean>;
+  }>;
+}
+
+interface AuditSink extends Adapter {
+  kind: 'audit';
+  emit(record: AuditRecord): Promise<void> | void;
+}
+
+interface ClientAdapter extends Adapter {
+  kind: 'client';
+  run<T>(action: ActionDef, input: unknown): Promise<ActionResult<T>>;
+}
+
+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;
+}
+
+interface EventBusAdapter extends Adapter {
+  kind: 'eventbus';
+  publish(event: DomainEvent): Promise<void> | void;
+  subscribe?(pattern: string, listener: (event: DomainEvent) => void): Unsubscribe;
+}
+
+interface LoggerAdapter extends Adapter {
+  kind: '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;
+  child(bindings: object): LoggerAdapter;  // pre-bind contexto (per-action, per-request)
+}
+```
+
+Ver §10 (Background), §11 (Eventos), §15 (RuntimeConfig) para detalhes de uso.
+
+### Server endpoints (auto-mount)
+
+Server adapter monta endpoints fixos + opcionais via `EndpointSpec`:
+
+| Path             | Default       | Auth   | Propósito                                     |
+|------------------|---------------|--------|-----------------------------------------------|
+| `/api/*`         | sempre        | varia  | Execução de actions registradas               |
+| `/health`        | enabled       | none   | Liveness probe — 200 se processo vivo         |
+| `/ready`         | enabled       | none   | Readiness — agrega `adapter.healthCheck()`    |
+| `/openapi.json`  | enabled       | none   | Spec OpenAPI gerada                           |
+| `/openapi/docs`  | dev only      | none   | Swagger UI                                    |
+| `/actions`       | disabled      | admin  | Catálogo de actions (debug)                   |
+| `/reactions`     | disabled      | admin  | Catálogo de reactions (debug)                 |
+| `/logs`          | disabled      | admin  | Query de logs (in-mem ou source custom)       |
+| `/audit`         | disabled      | admin  | Query de audit records                        |
+
+### Health check em duas camadas
+
+- **`/health`** — liveness probe simples. Responde 200 se o runtime iniciou e não morreu. Não chama dependência externa. Rápido, idempotente.
+- **`/ready`** — readiness probe. Chama `runtime.healthCheck()` que agrega `adapter.healthCheck?()` de todos os adapters. 200 se todos ok, 503 se algum falha. Toca DB, queue, bus.
+
+```ts
+runtime.healthCheck()
+// → {
+//     ok: true,
+//     adapters: {
+//       data:     { ok: true,  details: { latencyMs: 3 } },
+//       auth:     { ok: true },
+//       queue:    { ok: false, details: { error: 'Redis unreachable' } },
+//       eventBus: { ok: true },
+//     }
+//   }
+```
+
+`adapter.healthCheck()` é **opcional** — adapter que não implementa é considerado ok.
+
+Padrão Kubernetes/ECS/Cloud Run-compatible. Liveness mata pod se falhar (reinicia); readiness tira do load balancer se falhar (não mata).
+
+### Setup do runtime
+
+```ts
+import { createRuntime } from '@softize/opus/core'
+import { honoAdapter   } from '@softize/opus/server-hono'
+import { kyselyAdapter } from '@softize/opus/data-kysely'
+import { betterAuthAdapter } from '@softize/opus/auth-better-auth'
+import { pgAuditSink } from '@softize/opus/audit-pg'
+
+const runtime = createRuntime({
+  server:    honoAdapter({ app }),
+  data:      kyselyAdapter({ db }),
+  auth:      betterAuthAdapter({ client: auth }),
+  audit:     [pgAuditSink({ table: 'audit_log' })],
+  queue:     bullmqAdapter({ connection }),       // opcional — só se houver background action
+  eventBus:  mittEventBusAdapter(),               // opcional — só se houver emits
+})
+
+runtime.register(actions)            // monta tudo
+await runtime.start()
+```
+
+### Lifecycle de uma execução (sync)
+
+```
+HTTP request → Server adapter
+   ↓ (parse + resolve context via Auth adapter)
+ctx = { user, tenantId, can, db, emit, meta, ... }
+   ↓
+Runtime.execute(action, input, ctx)
+   ↓ (1) validate input contra schema
+   ↓ (2) load (se action declara `loads`)
+   ↓ (3) check public OR authenticate (ctx.user != null)
+   ↓ (4) authorize (chama action.authorize)
+   ↓ (5) handler executa
+            (durante: handler pode chamar ctx.emit(event, data)
+             → runtime publica via EventBusAdapter)
+   ↓ (6) validate output (em dev)
+   ↓ (7) emit audit pra todos AuditSinks
+   ↓ (8) build ActionResult
+   ↓
+Server adapter serializa → HTTP response
+```
+
+Erro em qualquer step (1-4) → handler **não executa**, audit registra falha, ActionResult.error.
+Erro no step 5 ou 6 → audit registra com erro, ActionResult.error.
+Erro em audit sink (step 7) → depende de `auditMode` ('lenient' default, 'strict' aborta).
+Falha em emit de evento (durante step 5) → depende de `emitMode` ('lenient' default).
+
+### Lifecycle (background)
+
+Quando action declara `background.enabled: true`, pipeline bifurca:
+
+```
+HTTP request → Server adapter
+   ↓ validate + authenticate + authorize (steps 1-4 acima)
+   ↓ QueueAdapter.enqueue(jobSpec)
+   ↓
+Server retorna JobHandle síncrono
+   ↓
+[worker, processo separado]
+   ↓ load → handler (com ProgressReporter se config) → validate output → audit
+   ↓ atualiza JobHandle.status = done/failed
+```
+
+Ver §10 (Background) para detalhes.
+
+### Versionamento de adapter
+
+Adapter declara `peerDependencies: { "@softize/opus/core": "^X.0.0" }`. Major bump do core = breaking. Patch/minor do adapter pode evoluir independente.
+
+### Adapters first-party vs comunidade
+
+O Opus mantém **first-party** as superfícies acima. Drivers iniciais por superfície são escolhidos pelo time core; drivers comunidade entram via PR no repo (são novos subpaths do mesmo pacote, não pacotes separados).
+
+Atualmente cobertos pelo time core (v0):
+- `@softize/opus/core`
+- `@softize/opus/server` (drivers: `/fastify` — `/hono` em v1)
+- `@softize/opus/data` (drivers: `/kysely`)
+- `@softize/opus/auth` (drivers: `/better-auth`)
+- `@softize/opus/client` (drivers: `/fetch`)
+- `@softize/opus/ui` (drivers: `/react`)
+- `@softize/opus/schema` (drivers: `/zod`)
+
+Outros drivers (Drizzle, Vue, Solid, NATS, etc) entram como contribuição quando houver demanda real.
+
+### O que adapter **não** decide
+
+- Shape de `ActionError`, `AuditRecord`, `ActionResult` — esses são contrato fechado do core.
+- Categorias de erro — fixas.
+- Nome dos campos de action — fixos.
+
+Adapter implementa o contrato; não modifica.
+
+---
+
+## 9. Princípios não-negociáveis
+
+Filtro pra qualquer adição ao Opus core. A pergunta:
+
+> *Isso é contrato que padroniza forma, ou é feature que faz trabalho?*
+
+**Contrato entra. Feature usa lib externa.**
+
+### Entra no core
+- Definição declarativa (`defineAction`, `defineEntity`, etc).
+- Tipos derivados e inferência ponta a ponta.
+- Contratos de erro, autorização, audit, paginação, envelope.
+- Catálogo de tipos lógicos.
+- Hooks/interfaces para adapters implementarem.
+
+### NÃO entra no core
+- Implementação de auth (RBAC engine, JWT, sessão).
+- Implementação de queue, cron, storage.
+- Implementação de ORM / DB client.
+- Componentes de UI prontos (são `@softize/opus/react`, separado do core).
+- Logger concreto (interface sim; implementação é adapter).
+- Error tracker, observability sink.
+- HTTP framework.
+- **Cache** — implementação fica fora. Core apenas declara intenção de invalidação via `invalidates: string[]`. Quem invalida (TanStack Query no client, Redis no server) é adapter/consumer.
+- **Carregamento de env vars** (`dotenv`, `t3-env` resolvem). Core nunca lê `process.env` direto — recebe valor pronto via `RuntimeConfig`.
+- **Process management** (PM2, restart loop). É deployment concern (Docker, k8s, systemd resolvem).
+
+### Adicionar coisa ao core requer
+1. Justificativa de por que é contrato e não feature.
+2. Uso real em pelo menos dois projetos distintos (ou um projeto + previsão concreta do segundo).
+3. Doc desta seção atualizada **antes** do código entrar.
+
+### Estilo de código
+
+Premissas transversais a todo código do core e adapters first-party.
+
+**Clean code, sempre.**
+- Funções/métodos curtos, uma responsabilidade clara.
+- Sem comentários óbvios; código autoexplicativo.
+- Comentário só pra explicar **porquê não-óbvio**, nunca **o que** o código faz.
+- Sem `any`, sem `// @ts-ignore`, sem `// eslint-disable` sem justificativa em PR.
+- Erro early-return; nunca pirâmide de `if` aninhado.
+
+**Naming elegante.**
+- Nomes revelam intenção, não implementação. `archiveDeal`, não `dealServiceArchiveMethod`.
+- Verbos pra actions (`archive`, `dispatch`, `validate`). Substantivos pra entidades (`Action`, `Runtime`, `Adapter`).
+- Sem abreviações herdadas de C (`ctx`, `req`, `res` são exceção convencional; `mgr`, `usr`, `cfg` não).
+- Plural só quando coleção real (`actions: Action[]`); singular pra factory que produz um (`defineAction`).
+- Booleanos com prefixo de pergunta: `isRetriable`, `hasIssues`, `canArchive`.
+
+**Híbrido fn × OO — regra de bolso.**
+
+| Use **função** quando | Use **classe** quando |
+|---|---|
+| Produz dado declarativo (`defineAction`, `error`, `t.email`) | Tem estado interno (`Runtime`, `ActionPipeline`) |
+| Pura ou determinística (formatador, validador) | Tem lifecycle (`init`, `dispose`) |
+| Composta como valor de primeira ordem (passar adiante, mapear) | Encapsula identidade (uma instância vive ao longo da app) |
+| Helper interno de módulo | Implementação de interface adapter |
+
+**Não-negociáveis:**
+- Nada de mixins, decorators do TC39 não-stable, ou herança profunda. Herança máxima: 1 nível (interface → classe).
+- Composição > herança. Sempre.
+- Sem singletons globais — quem precisa de instância única injeta via `Runtime`.
+- Imutabilidade por default. Mutação só em coleções internas de classes que **encapsulam** o mutável.
+- Sem `null` quando `undefined` cabe; sem `undefined` quando o tipo é colecional vazio (`[]`, `{}`).
+
+**Testes seguem o mesmo padrão.**
+- Test = mesma linguagem do código (`describe(Runtime, ...)`, não `describe('the runtime stuff', ...)`).
+- Arrange/act/assert visualmente separados.
+- Sem `beforeEach` setando state global; cada teste constrói o que precisa.
+
+---
+
+## 10. Background handler
+
+Action `simple` ou `form` pode declarar `background: BackgroundConfig` pra rodar em worker em vez de sync no request. Útil pra operações longas (reports, bulk, AI generation, importações).
+
+> Restringido a `simple`/`form`. `search`/`view` são reads que respondem direto; background pra eles não casa em v0.
+
+### Config
+
+```ts
+type BackgroundConfig = {
+  enabled:    true                      // explícito (sem default ambíguo)
+  queue?:     string                    // nome da fila (adapter-specific)
+  priority?:  'high' | 'normal' | 'low'
+  retry?:     { attempts: number, backoff?: BackoffSpec }
+  timeout?:   number                    // ms; 0 = sem timeout
+  progress?:  boolean                   // handler recebe ProgressReporter
+}
+
+type BackoffSpec =
+  | { kind: 'fixed',       delayMs: number }
+  | { kind: 'exponential', initialMs: number, multiplier?: number, maxMs?: number }
+```
+
+### Handler signature (background)
+
+```ts
+// sem progress
+handler: (ctx, input, loaded?) => Promise<Out>
+
+// com progress (background.progress: true)
+handler: (
+  ctx, input, loaded?,
+  progress: ProgressReporter,
+) => Promise<Out>
+
+type ProgressReporter = {
+  report(p: {
+    percent?: number     // 0..100
+    message?: string
+    data?:    unknown
+  }): Promise<void> | void
+}
+```
+
+### Result
+
+Background action **não retorna `Output` síncrono**. Retorna `JobHandle`:
+
+```ts
+type JobStatus = 'queued' | 'running' | 'done' | 'failed' | 'cancelled'
+
+type JobHandle<T = unknown> = {
+  jobId:        string
+  action:       string
+  status:       JobStatus
+  progress?:    { percent?: number, message?: string, data?: unknown }
+  data?:        T                       // populado quando status='done'
+  error?:       ActionError             // populado quando status='failed'
+  enqueuedAt:   string
+  startedAt?:   string
+  finishedAt?:  string
+  attempts:     number
+}
+```
+
+ActionResult de background action:
+
+```ts
+type BackgroundResult<T> =
+  | { ok: true,  data: JobHandle<T>, meta: ResultMeta }
+  | { ok: false, error: ActionError,  meta: ResultMeta }
+```
+
+### Pipeline (background)
+
+```
+HTTP request → Server adapter
+  ↓ (1) validate input
+  ↓ (2) authenticate
+  ↓ (3) authorize (sem load — load roda no worker)
+  ↓ (4) enqueue job via QueueAdapter
+  ↓
+Server retorna JobHandle síncrono → client polla ou subscribe
+  ↓
+Worker (processo separado) consome job:
+  ↓ (a) load
+  ↓ (b) handler (recebe ProgressReporter se config.progress)
+  ↓ (c) validate output
+  ↓ (d) audit
+  ↓ (e) atualiza JobHandle.status = done/failed
+```
+
+### Adapter: `QueueAdapter`
+
+```ts
+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
+}
+```
+
+Implementações futuras (não core): `@softize/opus/queue-bullmq`, `@softize/opus/queue-inngest`, `@softize/opus/queue-trigger-dev`.
+
+### Cliente
+
+`@softize/opus/react` expõe hook separado pra background:
+
+```ts
+const { run, job, progress, isRunning, isDone, cancel, error } =
+  useBackgroundAction(reportGenerate)
+
+await run({ template: 'monthly' })
+// job.jobId disponível imediato; UI acompanha progress
+```
+
+---
+
+## 11. Eventos de domínio
+
+Action `simple` ou `form` pode declarar `emits: string[]` — lista do que o handler **pode** emitir. Handler emite manualmente via `ctx.emit()`.
+
+> Restringido a `simple`/`form` em v0. Read kinds raramente emitem; promove quando aparecer dor.
+
+### Declaração (action) + emissão (handler)
+
+```ts
+defineAction({
+  name: 'deal.archive',
+  kind: 'simple',
+  // ...
+  emits: ['deal.archived', 'deal.statusChanged'],
+  handler: async (ctx, input) => {
+    const deal = await ctx.db.deals.archive(input.dealId)
+    await ctx.emit('deal.archived', { dealId: deal.id, at: deal.archivedAt })
+    if (deal.previousStatus !== 'archived') {
+      await ctx.emit('deal.statusChanged', {
+        dealId: deal.id, from: deal.previousStatus, to: 'archived',
+      })
+    }
+    return deal
+  },
+})
+```
+
+Runtime em dev mode emite warning se handler chamar `ctx.emit` com evento **não declarado** em `emits`. Em prod, runtime ainda emite (sem warning) — dev é fail-soft, contrato é informativo.
+
+### `ctx.emit`
+
+```ts
+type EmitFn = <T = unknown>(
+  event: string,
+  data: T,
+  meta?: { correlation?: string, [k: string]: unknown },
+) => Promise<void>
+```
+
+### Shape do evento
+
+```ts
+type DomainEvent<T = unknown> = {
+  type:      string                     // 'deal.archived'
+  id:        string                     // UUID único
+  timestamp: string                     // ISO 8601
+  actor:     { id: string | null, type?: 'user' | 'system' | 'integration' }
+  tenant?:   string | null
+  data:      T                          // payload (livre, handler decide)
+  source:    {
+    action:      string                 // 'deal.archive'
+    actionId:    string                 // bate com AuditRecord.id
+    correlation?: string                // request id / trace
+  }
+  meta?:     Record<string, unknown>
+}
+```
+
+### Adapter: `EventBusAdapter`
+
+```ts
+interface EventBusAdapter extends Adapter {
+  kind: 'eventbus'
+  publish(event: DomainEvent): Promise<void> | void
+}
+```
+
+Implementações (não core, adapter wrappa lib existente):
+- In-process: `@softize/opus/events-mitt` (default), `@softize/opus/events-nano`.
+- Distribuído: `@softize/opus/events-redis`, `@softize/opus/events-nats`, `@softize/opus/events-inngest`.
+
+### Falha de emit
+
+Igual audit: comportamento lenient default (warn no logger, action segue), strict configurável (`emitMode: 'strict'` aborta a action com `{ code: 'emit.failed', category: 'internal' }`).
+
+### Subscribers
+
+V0: consumer subscreve **imperativamente** no setup:
+
+```ts
+const bus = mittEventBusAdapter()
+bus.subscribe('deal.archived', async (event) => {
+  await sendNotification(event.data.dealId)
+})
+```
+
+`defineEventListener` declarativo entra em v1+ quando dor real de duplicar setup aparecer — subscribers têm dimensões próprias (ordering, dedup, retry, dead-letter) que merecem sub-protocolo dedicado.
+
+---
+
+## 12. Reactions
+
+Action é "ator inicia". Reaction é "sistema reage". Pareamento simétrico — ambos são declarativos, ambos são auto-registrados pelo runtime, ambos cumprem cinco papéis (declarar, autorizar, executar, auditar, propagar).
+
+### Contrato
+
+```ts
+type ReactionDef<Event = unknown> = {
+  // — Identidade —
+  name: string                                  // único, descritivo
+  on:   string | string[]                       // evento(s) a escutar
+  
+  // — Documentação —
+  description?: string
+  tags?:        string[]
+  
+  // — Execução —
+  handler: (ctx: ReactionContext, event: DomainEvent<Event>) =>
+             Promise<void> | void
+  
+  // — Resiliência —
+  retry?:       { attempts: number, backoff?: BackoffSpec }
+  timeout?:     number                          // ms
+  dedup?:       (event: DomainEvent<Event>) => string  // chave de idempotência
+  concurrency?: number                          // máx execuções paralelas (default 1)
+  
+  // — Autorização (raro) —
+  authorize?: (ctx: ReactionContext, event: DomainEvent<Event>) =>
+                boolean | Promise<boolean>
+}
+```
+
+### Exemplo
+
+```ts
+defineReaction({
+  name: 'hub.onCrmLeadCreated.syncSalesforce',
+  on:   'crm.lead.created',
+  description: 'Sincroniza leads novos do CRM com Salesforce',
+  tags: ['integration', 'salesforce'],
+  
+  retry:   { attempts: 3, backoff: { kind: 'exponential', initialMs: 1000 } },
+  timeout: 30_000,
+  dedup:   (event) => event.id,                 // dedup at-least-once
+  concurrency: 5,
+  
+  handler: async (ctx, event) => {
+    await syncToSalesforce(event.data.leadId)
+    await ctx.emit('hub.lead.synced', { leadId: event.data.leadId })
+  },
+})
+
+// Reactions com múltiplos eventos
+defineReaction({
+  name: 'analytics.onDealLifecycle',
+  on:   ['crm.deal.created', 'crm.deal.updated', 'crm.deal.archived'],
+  handler: async (ctx, event) => {
+    await analytics.track(event.type, event.data, event.actor)
+  },
+})
+```
+
+### `ReactionContext`
+
+Mais enxuto que `ActionContext` (sem input/loaded):
+
+```ts
+type ReactionContext = {
+  user:     User | null              // ator que disparou o evento (pode ser system)
+  tenantId: string | null
+  db:       unknown                  // mesmo data adapter
+  emit:     EmitFn                   // reaction pode emitir novos eventos (chain)
+  log:      LoggerAdapter            // logger pre-bound com contexto da reaction
+  storage:  StorageAdapter | null    // storage de arquivos (experimental)
+  provenance: Provenance             // { kind: 'reaction', … }
+  meta:     Record<string, unknown>
+}
+```
+
+Reaction pode emitir eventos novos via `ctx.emit` — habilita workflows declarativos em cadeia (`lead.created` → reaction → `lead.onboarded` → outra reaction → ...).
+
+### Setup unificado
+
+Runtime aceita actions e reactions misturados; distingue pelo discriminator interno:
+
+```ts
+runtime.register([
+  // actions
+  archiveDeal,
+  createLead,
+  
+  // reactions
+  onCrmLeadCreated,
+  onDealArchivedNotifyOwner,
+])
+
+await runtime.start()
+// — Para cada action  → ServerAdapter.mount(action)
+// — Para cada reaction → EventBusAdapter.subscribe(reaction.on, wrappedHandler)
+```
+
+`runtime.start()` falha se houver reaction sem `EventBusAdapter` configurado (fail-fast em setup, não em runtime).
+
+### Resiliência: quem implementa o quê
+
+| Campo         | Implementação                            | Sem suporte do adapter      |
+|---------------|------------------------------------------|------------------------------|
+| `dedup`       | Core — cache LRU de `event.id` por reaction (TTL configurável) | Sempre funciona |
+| `retry`       | Adapter preferencial (Inngest, BullMQ); core fallback simples (in-memory backoff) | Warn em setup; core fallback ativo |
+| `timeout`     | Core — AbortController em volta do handler | Sempre funciona |
+| `concurrency` | Adapter (consumer groups); core fallback (semáforo) | Default `concurrency: 1` |
+
+Reaction declara intenção; runtime aplica o que core garante + delega o que adapter suporta. Se adapter não cobre algo declarado, **warning visível no boot** (não silencia falha de capability).
+
+### Falha de reaction não afeta o emissor
+
+Reaction roda **assíncrono** ao handler que emitiu o evento. Se reaction falha, é problema dela (retry / dead-letter via adapter); a action que emitiu o evento já completou.
+
+Falhas registradas no log do runtime + audit (entrada do tipo `'reaction.failed'`). Adapter de eventos pode rotear pra dead-letter (v1).
+
+### Pipeline de uma reaction
+
+```
+EventBusAdapter recebe evento (publish externo ou ctx.emit interno)
+   ↓
+matching: encontra reactions registradas pra esse padrão
+   ↓ (paralelo, com concurrency limit)
+para cada reaction:
+   ↓ (a) dedup check (se declarado)
+   ↓ (b) authorize (se declarado)
+   ↓ (c) handler executa (com timeout)
+   ↓ (d) handler emite eventos (opcional, via ctx.emit)
+   ↓ (e) audit (reaction completed/failed)
+   ↓ (f) retry se falhou e config permite
+```
+
+### O que **não** entra em v0
+
+- **`deadLetter: string`** — evento pra publicar em caso de falha total. Útil mas exige sub-protocolo (quem consome dead-letter, retenção, replay).
+- **`ordering: 'global' | 'by-key'`** — garantia de ordem de processamento. Caro de implementar, raro pra v0.
+- **Reaction `background`** — bus já é assíncrono; agendar mais um tier não compensa em v0.
+- **Reaction com input parametrizado pelo subscriber** — `on: { event, filter: ... }` filter inline. v0: filtra dentro do handler.
+
+---
+
+## 13. i18n e `I18nRef`
+
+O Opus é i18n-aware mas **i18n é opt-in**. Projetos mono-idioma (ex: tudo pt-BR) passam strings cruas; projetos multi-idioma passam refs.
+
+```ts
+type I18nRef =
+  | string                                  // valor literal (default = chave)
+  | { key: string, default: string }        // chave i18n + fallback
+```
+
+Resolução:
+- **Sem UI adapter com i18n configurado**: passthrough — string vira ela mesma; objeto retorna `default`.
+- **Com i18n configurado**: string é tratada como chave (`label: 'deal.archive'` → resolve `'deal.archive'` no catálogo); objeto resolve `key` com fallback pro `default`.
+
+Custo zero pra quem não precisa. Adapter UI decide como resolver.
+
+---
+
+## 14. Runtime config
+
+Adapters são "config externa" (você pluga ou não). Mas existem **behavior knobs** que controlam como o runtime se comporta: modo de falha, ambiente, defaults de resiliência, i18n. Esses ficam consolidados em `RuntimeConfig`.
+
+### Princípio: core nunca lê env
+
+`RuntimeConfig` recebe **valores literais**, não chaves de env. Consumer lê env (com a ferramenta que preferir) e passa valor pronto. Core fica testável, portável e funciona em ambientes esquisitos (edge runtime, worker sem env, etc).
+
+```ts
+// ✓ correto — valor literal
+auditMode: 'lenient'
+
+// ✓ correto — consumer resolve env, passa pronto
+auditMode: process.env.NODE_ENV === 'production' ? 'strict' : 'lenient'
+
+// ✗ errado — core lendo env
+auditMode: process.env.AUDIT_MODE  // se core fizesse isso, seria acoplamento
+```
+
+### Shape
+
+```ts
+type RuntimeConfig = {
+  // — Modos de falha —
+  auditMode?:  'lenient' | 'strict'           // default 'lenient'
+  emitMode?:   'lenient' | 'strict'           // default 'lenient'
+
+  // — Ambiente —
+  env?:        'development' | 'production' | 'test'   // informativo
+  dev?:        boolean                                  // habilita validações extras
+
+  // — Validação —
+  validateOutputInDev?:  boolean              // default true se dev
+  warnUndeclaredEmits?:  boolean              // default true se dev
+
+  // — Resiliência / dedup —
+  dedupCacheTtl?:        number               // ms, default 60_000
+  defaultRetry?:         { attempts: number, backoff?: BackoffSpec }
+
+  // — i18n —
+  i18n?: {
+    resolver?:      (ref: I18nRef, locale?: string) => string
+    defaultLocale?: string                    // ex: 'pt-BR'
+  }
+
+  // — Limites —
+  maxConcurrentActions?:    number            // default Infinity
+  maxConcurrentReactions?:  number            // default 10
+}
+```
+
+### Setup completo
+
+```ts
+import { createRuntime } from '@softize/opus/core'
+import { fastifyServer }   from '@softize/opus/server/fastify'
+import { kyselyData }      from '@softize/opus/data/kysely'
+import { betterAuth }      from '@softize/opus/auth/better-auth'
+import { pinoLogger }      from '@softize/opus/log/pino'
+import { pgAudit }         from '@softize/opus/audit/pg'
+import { bullmqQueue }     from '@softize/opus/queue/bullmq'
+import { redisEvents }     from '@softize/opus/events/redis'
+
+const runtime = createRuntime({
+  // — adapters —
+  server:   fastifyServer({ app }),
+  data:     kyselyData({ db }),
+  auth:     betterAuth({ client: auth }),
+  logger:   pinoLogger({ level: 'info' }),
+  audit:    [pgAudit({ table: 'audit_log' })],
+  queue:    bullmqQueue({ connection }),
+  eventBus: redisEvents({ connection }),
+
+  // — behavior knobs —
+  config: {
+    auditMode: 'lenient',
+    emitMode:  'strict',
+    env:       process.env.NODE_ENV === 'production' ? 'production' : 'development',
+    dev:       process.env.NODE_ENV !== 'production',
+    i18n: {
+      resolver:      i18next.t,
+      defaultLocale: 'pt-BR',
+    },
+    maxConcurrentReactions: 20,
+  },
+})
+
+runtime.register([archiveDeal, createLead, onCrmLeadCreated])
+await runtime.start()
+
+// Graceful shutdown
+process.on('SIGTERM', async () => {
+  await runtime.dispose()
+  process.exit(0)
+})
+```
+
+### Defaults sensatos por config
+
+Se você não passa `config`, o runtime usa:
+
+```ts
+{
+  auditMode: 'lenient',
+  emitMode:  'lenient',
+  env:       'development',         // assume dev até prova contrário
+  dev:       true,
+  validateOutputInDev:  true,
+  warnUndeclaredEmits:  true,
+  dedupCacheTtl:        60_000,
+  defaultRetry:         { attempts: 3, backoff: { kind: 'exponential', initialMs: 1000 } },
+  maxConcurrentActions:   Number.POSITIVE_INFINITY,
+  maxConcurrentReactions: 10,
+}
+```
+
+**Defaults são `dev`-friendly por padrão.** Produção exige passar `env: 'production'` + `dev: false` explicitamente. Postura: se você esqueceu de configurar, o pior caso é "rodando como dev em prod" (vai funcionar, com warnings) — não "rodando como prod em dev sem feedback".
+
+### Validação da config
+
+Core valida `RuntimeConfig` na `createRuntime` via schema (Zod interno). Config inválida → erro síncrono no boot, com mensagem clara. Não silencia.
+
+### O que `RuntimeConfig` **não** controla
+
+- Detalhes específicos de adapter (`bullmqAdapter({ ... })` config vai pro adapter, não pra RuntimeConfig).
+- Feature flags (LaunchDarkly/Unleash existem; integre via `meta` em action ou logger).
+- Carregamento de env (consumer faz; core não toca).
+
+---
+
+## 15. Entidades
+
+### Introdução
+
+Até aqui o protocolo declarou **ações** — o que *acontece*. Falta declarar o que *persiste*: as **entidades** do domínio (`Deal`, `User`, `Invoice`). Uma entidade é a descrição declarativa de um recorte de dado — seus campos, relações e índices — que serve de **fonte única** para tudo que toca aquele dado.
+
+Você declara a entidade uma vez. A partir dela, o Opus materializa:
+
+- O **tipo TypeScript** da linha (inferido, ponta a ponta).
+- Os **schemas** Zod de input/output que as actions consomem (`entityInsertSchema`, `entityUpdateSchema`, `entityRowSchema`).
+- A **migration** do banco (via adapter — ver "Materialização").
+- A **projeção** de `view`/`search`, sem redeclarar o shape na mão.
+
+> **O Opus não tem ORM.** `defineEntity` é **contrato**, não engine. Ele declara a forma e anexa metadata; quem executa query e roda migration é lib externa (Drizzle, Kysely) via adapter. Mesma regra do §9: *contrato entra, feature usa lib externa.* Igual `defineAction` não hospeda HTTP, `defineEntity` não persiste dado.
+
+### Definindo uma entidade
+
+`defineEntity` é puramente declarativo — nenhum efeito colateral acontece ao chamá-lo (igual `defineAction` e `defineDomain`). Em sucesso, devolve o próprio objeto tipado.
+
+```ts
+import { defineEntity, belongsTo, hasMany } from '@softize/opus/schema'
+import { t } from '@softize/opus/schema/zod'
+
+export const Deal = defineEntity({
+  name: 'deal',
+
+  fields: {
+    title:   t.string({ max: 200 }),
+    amount:  t.money({ currency: 'BRL' }),
+    status:  t.enum(['open', 'won', 'lost']).default('open'),
+    ownerId: t.uuid(),
+    notes:   t.text().nullable(),
+  },
+
+  relations: {
+    owner:       belongsTo('user',     { from: 'ownerId' }),
+    company:     belongsTo('company',  { from: 'companyId' }),
+    attachments: hasMany('attachment', { to: 'dealId' }),
+  },
+
+  indexes: [
+    { on: ['ownerId'] },
+    { on: ['status', 'createdAt'] },
+  ],
+
+  timestamps: true,
+  softDelete: true,
+})
+```
+
+### Convenções
+
+O Opus assume defaults sensatos para você não repetir o óbvio. Toda convenção tem override explícito.
+
+**Nome e tabela.** `name` é o nome **singular** da entidade (`[a-z][a-zA-Z0-9_]*`, igual domínio — espelha "substantivo pra entidade" do §9). O nome da tabela é o plural de `name` por default; declare `table` para sobrescrever:
+
+```ts
+defineEntity({ name: 'person', table: 'people', /* ... */ })
+```
+
+**Chave primária.** Se você não declarar uma PK, o Opus injeta `id: t.uuid().pk()`. Para uma PK própria, declare-a:
+
+```ts
+fields: { code: t.string().pk(), /* ... */ }   // sem id automático
+```
+
+**Timestamps.** `timestamps: true` injeta `createdAt` e `updatedAt` (geridos pelo runtime — o handler nunca seta na mão). Default é `false`.
+
+**Soft delete.** `softDelete: true` injeta `deletedAt`. Actions `search`/`view` filtram registros deletados por default; passe a opção explícita quando quiser incluí-los.
+
+### Campos
+
+Campos reusam o **catálogo de tipos lógicos** do §7 (`t.email`, `t.money`, `t.datetime`...). A metadata que cada tipo já carrega (`logicalType`) é o que permite o adapter de DB mapear a coluna certa (`datetime` → `timestamp`, `money` → `numeric + currency`) sem você dizer nada.
+
+Um campo tem **duas camadas independentes** — não as misture:
+
+| Camada | Modifiers | Quem consome |
+|---|---|---|
+| **Validação** (Zod nativo) | `.max()`, `.min()`, `.nullable()`, `.default()`, `.optional()` | runtime valida input da action |
+| **Coluna** (metadata opus) | `.pk()`, `.unique()`, `.references()`, `.index()` | adapter de migration / data |
+
+```ts
+fields: {
+  id:      t.uuid().pk(),
+  email:   t.email().unique(),                       // validação + constraint
+  slug:    t.slug().unique().index(),
+  ownerId: t.uuid().references('user'),              // FK explícita (sem relation)
+  bio:     t.text().nullable(),                      // coluna NULL-able
+  tier:    t.enum(['free', 'pro']).default('free'),  // default no schema E no DDL
+}
+```
+
+`t.uuid().pk()` produz `{ logicalType: 'uuid', column: { pk: true } }` — a validação segue sendo Zod puro; o `column` é o canal que o adapter lê. Schema bruto (`z.string()`) continua aceito num campo, só perde a adaptação automática (cai pra `text`).
+
+### Relações
+
+Relações são declaradas com helpers puros que referenciam a outra entidade **por string** (não por import), evitando ciclos. O runtime resolve o grafo no `register`, validando que os alvos existem.
+
+| Helper | Forma | Significado |
+|---|---|---|
+| `belongsTo(target, { from })` | FK local | `deal.ownerId` → `user.id` |
+| `hasOne(target, { to })` | FK no alvo, 1:1 | `user.id` → `profile.userId` |
+| `hasMany(target, { to })` | FK no alvo, 1:N | `deal.id` → `attachment.dealId` |
+| `manyToMany(target, { through })` | tabela de junção | `deal` ↔ `tag` via `deal_tags` |
+
+```ts
+relations: {
+  owner:       belongsTo('user',       { from: 'ownerId' }),
+  attachments: hasMany('attachment',   { to: 'dealId' }),
+  tags:        manyToMany('tag',       { through: 'deal_tags' }),
+}
+```
+
+> **Sem lazy-loading mágico.** Relação é *contrato* (quem aponta pra quem), não carregamento automático. O `view`/`search` declara o que expandir via `projection`/`expand` (§2); o adapter de data resolve o join. O Opus nunca dispara query implícita ao acessar uma propriedade.
+
+### Índices e constraints
+
+```ts
+indexes: [
+  { on: ['ownerId'] },                       // índice simples
+  { on: ['status', 'createdAt'] },           // composto
+  { on: ['email'], unique: true },           // unique multi-coluna
+  { on: ['title'], using: 'gin' },           // hint de tipo; adapter resolve
+]
+```
+
+Constraints de coluna única ficam no campo (`.unique()`); constraints multi-coluna ficam em `indexes`. O adapter traduz para o DDL do banco-alvo.
+
+### Tipo inferido e schemas derivados
+
+A entidade é a fonte do tipo TS e dos schemas que as actions consomem — declarado uma vez, inferido em todo lugar.
+
+```ts
+import type { EntityRow, EntityInsert, EntityUpdate } from '@softize/opus/schema'
+
+type DealRow = EntityRow<typeof Deal>
+// { id: string; title: string; amount: bigint;
+//   status: 'open' | 'won' | 'lost'; ownerId: string; companyId: string;
+//   notes: string | null; createdAt: string; updatedAt: string; deletedAt: string | null }
+```
+
+Os schemas Zod pra input/output de actions são **funções** sobre a entidade (não
+props anexadas — mantém o `defineEntity` identity-puro):
+
+```ts
+import { entityRowSchema, entityInsertSchema, entityUpdateSchema } from '@softize/opus/schema'
+
+entityRowSchema(Deal)    // Zod da linha completa (output)
+entityInsertSchema(Deal) // sem campos gerados; nullable/default opcionais (create)
+entityUpdateSchema(Deal) // partial do insert (update)
+```
+
+### Materialização
+
+A entidade materializa em quatro direções; só a primeira precisa de um adapter externo.
+
+```
+defineEntity
+   ├─►  EntityRow + entityRowSchema/InsertSchema/UpdateSchema   (tipos + Zod, schema)
+   ├─►  kyselyRepo(db, entity): CRUD tipado                      (driver Kysely)
+   ├─►  crudActions(entity, {authorize}): actions de CRUD        (driver Kysely)
+   └─►  entityColumns → drift-check / scaffold / migrate         (opus db check/scaffold/migrate)
+```
+
+> **O Opus não roda migração própria nem tem ORM.** Engine de query, runner de
+> migration e introspecção são do **Kysely**; o `defineEntity` é a fonte única; o
+> ciclo é `up/down` à mão (scaffold opcional) + **drift-check**. Decisão completa
+> e o porquê de não adotar Drizzle/Atlas como base em `docs/data-layer.md`.
+
+### Derivando actions da entidade
+
+O scaffolding entidade→CRUD vive na **camada de composição** (driver Kysely), não
+no core: `crudActions` gera as actions com input/output derivados e handlers backed
+por `kyselyRepo`. Decisão (a fronteira schema↔core): pôr `entity:` no `defineAction`
+e `ctx.repo` no `ActionContext` puxaria tipos de entidade pro core e criaria ciclo —
+então a composição mora onde core+schema já convivem (ver `data-layer.md`, peça 7).
+
+```ts
+import { crudActions, kyselyRepo } from '@softize/opus/data/kysely'
+
+// gera deal.view/create/update/delete/search (só as ops com authorize)
+export const dealActions = crudActions(Deal, {
+  view:   (ctx) => ctx.can('deal:read'),
+  create: (ctx) => ctx.can('deal:create'),
+  update: (ctx) => ctx.can('deal:update'),
+  delete: (ctx) => ctx.can('deal:delete'),
+  search: (ctx) => ctx.can('deal:read'),  // output Paginated; offset + filtros de igualdade (v1)
+})
+
+// quando precisa de lógica própria, action manual + repo + schemas da entidade:
+defineAction({
+  name: 'deal.archive',
+  kind: 'simple',
+  input: z.object({ id: t.uuid().zod() }),
+  output: entityRowSchema(Deal),
+  authorize: (ctx) => ctx.can('deal:archive'),
+  handler: (ctx, input) => kyselyRepo(ctx.db, Deal).update(input.id, { /* ... */ }),
+})
+```
+
+`kyselyRepo(ctx.db, Deal)` é o repositório tipado (insert/findById/update/remove/list)
+— casca fina sobre Kysely, não ORM com estado.
+
+**Naming (camel ↔ snake).** O backend é camelCase; o snake mora só no banco. O
+`CamelCasePlugin` do Kysely faz a ponte de query/DDL; o Opus só mapeia no
+**drift-check** (a introspecção volta crua). `naming` no `opus.config.ts` (default
+`snake`). Detalhes e o footgun auto-denunciado em `docs/data-layer.md`.
+
+### Entidades dentro de um domínio
+
+`DomainConfig.models` recebe as entidades do recorte (substitui o `unknown` placeholder atual). O domínio agrupa; a entidade declara.
+
+```ts
+import { defineDomain } from '@softize/opus'
+
+export const crm = defineDomain({
+  name: 'crm',
+  models: { Deal, Company, Contact },
+  actions: { /* deal.create, deal.search, ... */ },
+})
+```
+
+### O que **não** entra
+
+- **ORM / Active Record.** Sem `deal.save()`, sem estado na instância. Entidade é descrição, não objeto vivo.
+- **Query DSL próprio.** Filtro/sort/join de action saem do contrato (§2); query ad-hoc usa Kysely/Drizzle direto.
+- **Lazy-loading / N+1 mágico.** Expansão é sempre declarada (`projection`/`expand`).
+- **Migration runner próprio.** Drizzle-kit roda; o Opus só gera o schema.
+- **Hooks de ciclo de vida da linha** (`beforeSave`, `afterDelete`). Efeito de negócio é **action** + **reaction** (§12), não gancho escondido no model.
+
+---
+
+## 16. Glossário
+
+- **Action** — unidade declarativa que flui pelo pipeline opus. Ver §2.
+- **Kind** — discriminator de action: `simple`, `form`, `search`, `view`. Determina shape do contrato.
+- **`defineAction`** — função que constrói uma action a partir do contrato declarativo. Aceita union de todos os kinds.
+- **`defineContract`** — constrói só o **contrato** (`ActionDef` sem handler/loads/execução); roda nos dois lados (`shared`). Ver §2.
+- **`bindAction`** — amarra o server-only (`handler`/`loads`/...) a um contrato, produzindo um `ActionDef`. `authorize` do binding (row-level) sobrescreve o do contrato. Ver §2.
+- **`ActionContract` / `ActionBinding`** — o contrato declarativo e a parte server-only que o `bindAction` junta.
+- **`SimpleAction` / `FormAction` / `ListAction` / `ViewAction`** — variantes do `ActionDef` (discriminated union).
+- **Projection** — campos/relações sempre carregados em uma view action.
+- **Paginated<T>** — envelope de output de search actions: `{ items, cursor, total? }`.
+- **Adapter** — código que conecta opus a uma stack concreta (server framework, ORM, UI lib). Ver §8.
+- **Runtime** — orquestrador no centro: recebe action + input + ctx, executa pipeline (validate → load → authorize → handle → audit → result).
+- **Contract** — promessa de comportamento declarada na action que um adapter materializa.
+- **Handler** — função que executa a mudança. Uma das partes da action.
+- **Loader** — função declarada em `loads` que pré-carrega recurso antes de `authorize` rodar. Ver §4.
+- **Schema** — descrição de input/output validável compatível com `StandardSchemaV1`. Default: Zod.
+- **Logical type** — semântica conhecida de um campo (`email`, `money`, `datetime`...) com metadata anexada que adapters consomem. Ver §7.
+- **`ActionResult<T>`** — envelope discriminated union retornado de toda execução: `{ ok: true, data, meta } | { ok: false, error, meta }`. Ver §6.
+- **`ActionError`** — shape padronizado de erro emitido por uma action. Ver §3.
+- **`ValidationIssue`** — item dentro de `ActionError.issues` para erros multi-campo.
+- **`AuditRecord`** — registro emitido após execução de action. Ver §5.
+- **Sink** — destino que recebe `AuditRecord`. Múltiplos sinks possíveis. Ver §5.
+- **Invalidates** — chaves de cache que devem ser marcadas stale após uma action.
+- **Idempotency key** — string que identifica execução única; repetições com mesma chave retornam o resultado da primeira.
+- **Fail-closed** — default seguro: action sem `authorize` é negada. Ver §4.
+- **`FieldSpec`** — descrição declarativa de campo em form action (label, widget, options, condicionais). Ver §2.
+- **`FilterSpec`** — descrição declarativa de filtro em search action (mode server/client, operators, options). Ver §2.
+- **`OptionsSpec`** — discriminated union para fonte de opções: `static` (inline), `dictionary` (catálogo nomeado), `lookup` (async). Ver §2.
+- **`I18nRef`** — `string` (literal/passthrough) ou `{ key, default }` (i18n com fallback). Opt-in. Ver §12.
+- **`BackgroundConfig`** — configura execução em worker. Apenas `simple`/`form`. Ver §10.
+- **`ProgressReporter`** — interface injetada como 4º arg do handler quando `background.progress: true`. Ver §10.
+- **`JobHandle<T>`** — retorno síncrono de background action; representa execução assíncrona. Ver §10.
+- **`JobStatus`** — `'queued' | 'running' | 'done' | 'failed' | 'cancelled'`. Ver §10.
+- **`DomainEvent<T>`** — evento de domínio emitido pelo handler via `ctx.emit`. Ver §11.
+- **`EventBusAdapter`** — adapter que publica `DomainEvent` (in-process ou distribuído). Ver §8/§11.
+- **`QueueAdapter`** — adapter que executa background jobs. Ver §8/§10.
+- **`ctx.emit`** — função disponível no contexto do handler para emitir eventos declarados em `emits`. Ver §11.
+- **`requires`** — permissão declarativa (string ou array) usada por adapters de docs/OpenAPI. Distinta de `authorize` (lógica runtime). Ver §4.
+- **`automatable`** — flag que indica se a action pode ser disparada por sistema (cron, workflow, trigger). Distinta de `ai.enabled`. Ver §2.
+- **`internal`** — flag que indica action service-to-service apenas; server adapter não expõe como REST público. Ver §2.
+- **Reaction** — declaração que escuta evento(s) e executa handler. Auto-registrada pelo runtime via EventBusAdapter. Pareada com Action (ator inicia × sistema reage). Ver §12.
+- **`defineReaction`** — função que constrói uma reaction declarativa.
+- **`ReactionContext`** — contexto entregue ao handler de reaction (user, tenant, db, emit, log, meta).
+- **`dedup`** — função em reaction que produz chave de idempotência; runtime descarta evento já processado. Ver §12.
+- **`LoggerAdapter`** — interface de logger plugável (levels, structured, child binding). Default: `@softize/opus/log-console`. Ver §8.
+- **`RuntimeConfig`** — behavior knobs do runtime (auditMode, emitMode, env, i18n, limits). Recebe valores literais; core nunca lê env direto. Ver §14.
+- **`healthCheck()`** — método opcional em qualquer adapter, retorna `{ ok, details? }`. Agregado por `runtime.healthCheck()` e exposto em `/ready`. Ver §8.
+- **`/health`** — liveness probe; 200 se processo vivo. Não toca dependência externa. Ver §8.
+- **`/ready`** — readiness probe; agrega `adapter.healthCheck()`. 503 se algum adapter falha. Ver §8.
+- **`EndpointSpec`** — config passada ao ServerAdapter pra ligar/desligar endpoints opcionais (`/logs`, `/audit`, `/actions`, `/reactions`). Ver §8.
+- **Entity** — descrição declarativa de um recorte de dado persistido (campos, relações, índices). Fonte única para tipo, schemas, projeção e migration. Ver §15.
+- **`defineEntity`** — função que constrói uma entidade a partir do contrato declarativo. Puro, sem efeito colateral.
+- **Relation** — declaração de vínculo entre entidades (`belongsTo`, `hasOne`, `hasMany`, `manyToMany`), referenciada por string e resolvida no `register`. Ver §15.
+- **`EntityRow<E>` / `EntityInsert<E>` / `EntityUpdate<E>`** — tipos inferidos da entidade: linha completa, input de create (sem campos gerados), partial de update. Ver §15.
+- **`kyselyRepo(db, Entity)`** — repositório tipado (CRUD) derivado de uma entidade pelo driver Kysely; casca fina, não ORM. Ver §15.
+- **`crudActions(Entity, authorize)`** — gera as opus actions de CRUD da entidade (driver Kysely), handlers backed por `kyselyRepo`. Composição, não core. Ver §15.
+
+---
+
+## Decisões em aberto
+
+- Licença (MIT, Apache-2.0, AGPL).
+- Política de versionamento (semver convencional vs calver).
+- Estratégia de release (changesets vs custom).