@softize/opus 22.0.0 → 22.2.0

package/src/testing/index.ts

@@ -206,9 +206,13 @@ export interface TestableAction<In, Out, ParsedIn = In> {
   authorize?: AuthorizeSpec<ParsedIn>
   input: Schema<In, ParsedIn>
   output: Schema<Out> | Schema<unknown, Out>
-  /** Opcional: contrato puro (sem handler) executa via `mockHandler` em modo design. */
+  /** Opcional: contrato puro (sem handler) só executa pelo `mockHandler` obsoleto. */
   handler?: HandlerFn<ParsedIn, Out>
-  /** Em `OPUS_MODE=design` vence o handler real — mesma régua do runtime. */
+  /**
+   * Em `OPUS_MODE=design` vence o handler real — mesma régua do runtime.
+   *
+   * @deprecated Desde a 22.1.0 (ADR 0037); teste a action ligada ao handler.
+   */
   mockHandler?: HandlerFn<ParsedIn, Out>
 }
 
@@ -329,7 +333,7 @@ export async function runAction<In, Out, ParsedIn = In>(
     throw error({
       code: 'testing.no_handler',
       category: 'internal',
-      message: `Action "${action.name}" não tem handler executável — contrato puro roda em modo design (OPUS_MODE=design) com mockHandler; fora dele, teste o ActionDef do bindAction`,
+      message: `Action "${action.name}" não tem handler executável: teste o ActionDef produzido pelo bindAction. Os dados do modo design são gerados pelo plugin opusDesign() e não são comportamento da action.`,
     })
   }
   const raw = await handlerToRun(ctx, parsed, loaded)

package/src/ui/docs/content/actions.md

@@ -132,7 +132,7 @@ nessa estrutura. Os grupos seguem esta sequência; dentro de cada grupo, a ordem
 ```text
 name, kind
   → label, title, summary, description, icon, color, messages, tags, examples, errors
-  → input, output
+  → input, output, effect, personalData
   → public, requires, authorize, loads
   → handler, mockHandler
   → audit, confirm, invalidates, rateLimit, idempotency
@@ -146,60 +146,97 @@ Declare `input` e `output` com `z.object` e use os tipos lógicos do catálogo e
 validações: `z.object({ tag: t.slug().zod(), contato: t.email().zod() })`. O `.zod()` devolve o
 schema zod de cada tipo lógico (slug, email, phone, money…), importado de `@softize/opus/schema/zod`.
 
+## Declarar o que a action faz com os dados
+
+Dois fatos sobre a action valem para qualquer consumidor, da interface à IA, e ficam declarados no
+contrato:
+
+- **`effect`** diz se a action só lê (`'read'`) ou altera estado (`'write'`). `list` e `view` já são
+  leitura, porque são servidas por `GET`, e não precisam declarar. `simple` e `form` declaram,
+  porque o `kind` não diz isso: uma análise sob demanda costuma ser `simple` e só ler.
+- **`personalData`** diz se a resposta contém dados que identificam pessoas, como nome, documento,
+  contato, placa ou texto livre sobre alguém. `false` também é uma declaração.
+
+```ts
+export const salesPerformanceContract = defineContract({
+  name: 'sales.performance',
+  kind: 'simple',
+  input: z.object({ period: z.string() }),
+  output: z.object({ total: z.number() }),
+  effect: 'read',
+  personalData: false,
+})
+```
+
+Com `personalData: true`, toda execução bem-sucedida fica marcada no registro de auditoria com a
+quantidade de registros devolvidos, inclusive quando a action declara `audit: false`; nesse caso o
+registro é mínimo, sem entrada nem saída. No modo design, a resposta simulada não é marcada. Um
+host de IA pode usar `effect` para decidir o que oferecer ao modelo sem procedimento, e o MCP publica
+a anotação `readOnlyHint`. O `opus check` avisa quantas actions ainda não declaram os dois fatos; uma
+major futura passará a exigi-los.
+
 A autorização é fechada por padrão: sem `public: true`, a action exige usuário autenticado; com
 `authorize`, exige também a permissão declarada. `automatable: true` permite que um
 [schedule](/docs/scheduler) execute a action como o sistema, sem abri-la a chamadores anônimos.
 
 ## Prototipar com dados simulados
 
-Para desenhar a interface antes de o backend existir, declare um `mockHandler` no contrato. Com
-`OPUS_MODE=design`, o runtime executa o `mockHandler` no lugar do `handler`; sem ele, usa o
-`handler` real. Como o mock fica no contrato, a mesma declaração serve ao design e, depois, ao
-handler real, e o mock não precisa acessar `ctx.db`.
+Para desenhar a interface antes de o backend existir, rode o app em modo design. Nesse modo, toda
+action responde sem que o contrato declare nada: a resposta é gerada pelo `fake` a partir do
+`output` do contrato (ADR 0037).
+
+- A mesma requisição recebe sempre a mesma resposta.
+- Uma `list` devolve três páginas do tamanho pedido em `limit` (20 quando a entrada não pede, até
+  100) e respeita a paginação declarada. Busca e filtros não filtram o dado gerado.
+- Quando a entrada e a saída têm `id`, a saída repete o `id` da entrada, desde que o schema da saída
+  aceite esse valor. Assim, abrir um item da lista mostra o mesmo identificador.
 
-`fake` e `fakeMany` geram dados determinísticos a partir do próprio schema (ver
-[Testes de action](/docs/testing)). Em `list`, o `mockHandler` devolve a página inteira, com
-`items`, `cursor` e `total`:
+O dado gerado tem o formato certo, mas não segue a regra de negócio: os valores de um enum são
+sorteados, e uma listagem e um detalhe só coincidem no `id`. Quando o design precisa de coerência,
+como um item em cada situação ou algo criado que aparece na lista, escreva um cenário. Ele fica fora
+do contrato e é ligado à action pelo nome:
 
 ```ts
-import { bindAction, defineContract } from '@softize/opus/core'
-import { entityRowSchema } from '@softize/opus/schema'
-import { fake, fakeMany } from '@softize/opus/testing'
-import { z } from 'zod'
-import { EventEntity } from '../entity.ts'
+import { defineDesignScenario } from '@softize/opus/design'
+import { eventGet, eventList } from '../domains/event/contract.ts'
+
+// Valor fixo: o caso mais comum.
+export const eventsInEachState = defineDesignScenario(eventList, {
+  items: [
+    { id: 'e1', title: 'Revisão agendada', status: 'scheduled' },
+    { id: 'e2', title: 'Revisão perdida', status: 'lost' },
+  ],
+  cursor: { next: null },
+  total: 2,
+})
 
-// `entityRowSchema` deriva da entidade o schema de uma linha.
-const eventRowSchema = entityRowSchema(EventEntity)
+// Função: quando a resposta depende da entrada.
+export const eventDetail = defineDesignScenario(eventGet, (input) => ({
+  id: input.id,
+  title: 'Revisão agendada',
+  status: 'scheduled',
+}))
+```
 
-export const eventGet = defineContract({
-  name: 'event.get',
-  kind: 'view',
-  input: z.object({ id: z.string().uuid() }),
-  output: eventRowSchema,
-  mockHandler: () => fake(eventRowSchema),
-})
+A resposta é tipada pela entrada e pela saída do contrato; em `list`, é a página inteira. Informe ao
+plugin onde os cenários estão, com caminhos ou globs:
+`opusDesign({ scenarios: 'design/scenarios/*.ts' })`. O cenário vence a resposta gerada. Um cenário
+de uma action que não existe, ou dois cenários para a mesma action, impedem o runtime de design de
+subir, e o erro lista os nomes.
 
-export const eventList = defineContract({
-  name: 'event.list',
-  kind: 'list',
-  input: z.object({}),
-  output: eventRowSchema,
-  paginate: 'cursor',
-  mockHandler: async () => ({ items: fakeMany(eventRowSchema, 20), cursor: { next: null }, total: 20 }),
-})
+O Opus não decide onde os cenários ficam nem se entram no repositório. Eles não fazem parte da
+aplicação: podem ficar numa pasta ignorada pelo git e ser escritos durante a sessão de design,
+quando forem necessários.
 
-// Depois, o servidor liga o handler real ao mesmo contrato.
-export const eventGetImpl = bindAction(eventGet, {
-  handler: async (ctx, input) =>
-    ctx.db.selectFrom('events').selectAll().where('id', '=', input.id).executeTakeFirstOrThrow(),
-})
-```
+`mockHandler` está obsoleto desde a 22.1.0 e sai na próxima major. Enquanto existir, ele ainda
+responde no modo design, abaixo do cenário e acima da resposta gerada, e o `opus check` conta
+quantas actions ainda o declaram. Para migrar, apague o `mockHandler`; se a resposta dele importar
+para o design, transforme-a em cenário.
 
-O `mockHandler` roda no servidor, não no navegador. O plugin `opusDesign()`, de
-`@softize/opus/vite`, monta o runtime do Opus dentro do dev server e responde `/api` no próprio
-processo. No modo design, qualquer `server.proxy` para um backend externo fica desligado: um prefixo
-que ia para o proxy e não tem action correspondente responde 503 em envelope, sem alcançar o
-backend. A aplicação chama `/api` como sempre e recebe os dados simulados.
+O plugin `opusDesign()`, de `@softize/opus/vite`, monta o runtime do Opus dentro do dev server e
+responde `/api` no próprio processo. No modo design, qualquer `server.proxy` para um backend externo
+fica desligado: um prefixo que ia para o proxy e não tem action correspondente responde 503 em
+envelope, sem alcançar o backend. A aplicação chama `/api` como sempre e recebe os dados simulados.
 
 ```ts
 // vite.config.ts — o plugin só carrega no modo design, por import dinâmico.
@@ -233,9 +270,7 @@ nem reiniciar o dev server. Quando uma action não é encontrada, o plugin recon
 vez por ciclo de mudança e tenta de novo; se a action continuar ausente, a resposta indica o
 `entry` a conferir.
 
-Como o contrato vai para os dois lados, o `mockHandler` também entra no bundle da web, onde nunca é
-chamado. Não o condicione com `import.meta.env` no contrato: essa variável não existe no Node e
-quebraria o servidor.
+Os cenários não entram no bundle da web: eles ficam fora do contrato, e só o plugin os carrega.
 
 ## Consumir o contrato na interface
 

package/src/ui/docs/content/mcp.md

@@ -56,6 +56,12 @@ entrada. Em `_meta`, cada tool traz os
 [Produtos de Dados](/docs/data-products) relacionados: `com.softize.opus/data-products` lista os
 identificadores e `com.softize.opus/data-product-labels`, o nome legível de cada um.
 
+Quando a action declara o que faz com os dados, a tool traz também as anotações padrão do MCP:
+`readOnlyHint` vem de `effect`. Numa action que escreve, `destructiveHint` vai sempre explícito, a
+partir de `ai.destructive`, porque o MCP trata a ausência numa escrita como destrutiva.
+Em `_meta`, `com.softize.opus/effect` repete o efeito e `com.softize.opus/personal-data` diz se a
+resposta contém dado pessoal. Veja [Actions](/docs/actions).
+
 `CallTool` recusa com erro qualquer nome fora dessa lista; os demais seguem por `runtime.execute`.
 A exposição declarada em `ai` decide o que o cliente MCP pode executar, e a autorização do contexto
 continua valendo sobre ela. Para um acesso somente de leitura, exponha apenas actions de leitura.

package/src/ui/docs/content/testing.md

@@ -15,8 +15,8 @@ pulada, porque o schema descreve o item e o handler devolve a página. Falhas us
 `ActionError` tipado do runtime, como `validation.invalid_input`, `auth.unauthenticated`,
 `auth.system_forbidden` e `auth.forbidden`.
 
-Passe a action ligada ao handler, produzida por `bindAction`. O contrato puro não tem handler e só
-executa em modo design, descrito abaixo.
+Passe a action ligada ao handler, produzida por `bindAction`. O contrato puro não tem handler e
+falha com `testing.no_handler`.
 
 ```ts
 import { runAction } from '@softize/opus/testing'
@@ -86,29 +86,13 @@ const { output, emitted, logged } = await runAction(taskDone, { id: '1' }, { use
 expect(emitted).toEqual([{ event: 'task.done', data: { id: '1' } }])
 ```
 
-## Testar em modo design
+## Dados do modo design
 
-Com `OPUS_MODE=design`, `runAction` executa o `mockHandler` quando ele existe, como o runtime do
-modo design. Nesse modo, o contrato puro também é testável. Fora dele, um contrato sem handler falha
-com `testing.no_handler`.
-
-```ts
-import { afterEach, it } from 'vitest'
-import { runAction } from '@softize/opus/testing'
-import { Task, taskList } from './list.ts'
-
-afterEach(() => {
-  // A variável vale para o processo inteiro; limpe para não afetar outros testes.
-  delete process.env['OPUS_MODE']
-})
-
-it('o mock devolve itens válidos para o schema', async () => {
-  process.env['OPUS_MODE'] = 'design'
-  const { output } = await runAction(taskList, {}, { user: { id: 'u1' } })
-  // `list` não valida a saída no pipeline: confira item a item.
-  for (const item of output.items) expect(Task.safeParse(item).success).toBe(true)
-})
-```
+Os dados que o modo design mostra não são comportamento da action e não precisam de teste de
+unidade: o plugin `opusDesign()` os gera a partir do contrato (ver
+[Actions](/docs/actions)). Enquanto o `mockHandler` existir, obsoleto desde a 22.1.0,
+`runAction` com `OPUS_MODE=design` ainda o executa, como o runtime. Teste a action ligada ao
+handler em vez dele.
 
 ## memStorage
 
@@ -126,7 +110,7 @@ expect(storage.keys()).toEqual(['notas/9.pdf'])
 ## fake — dados gerados pelo schema
 
 `fake(schema)` e `fakeMany(schema, n)` geram dados sintéticos determinísticos que satisfazem o
-schema zod. Servem ao `mockHandler` do modo design e a fixtures de teste. A mesma `seed` produz a
+schema zod. Servem à resposta gerada do modo design e a fixtures de teste. A mesma `seed` produz a
 mesma saída, sem `Math.random`. Os valores seguem as validações do zod (email, uuid, url, datetime)
 e o nome do campo (email, id, `*At` como data, telefone, CPF/CNPJ, nome…), com conteúdo em pt-BR.
 

package/src/vite/design.ts

@@ -6,7 +6,7 @@
  * Antes, o dev server proxeava `/api` pra um backend real — o que vaza escrita
  * pra prod e exige infra de pé pra desenhar tela. Com o plugin, `vite --mode
  * design` monta o runtime (driver `nodeServer`) no próprio dev server: os
- * `mockHandler` dos contratos respondem (`OPUS_MODE=design`), qualquer proxy
+ * actions respondem pelos dados de design (ADR 0037), qualquer proxy
  * configurado é DESLIGADO (prefixo ex-proxy sem cobertura responde 503 em
  * envelope, nunca vaza), e o Maestro sonda `GET /__opus/design` pra saber que
  * o preview está montado.
@@ -44,6 +44,7 @@ import {
   isDomainConfig,
   isReaction,
   isSchedule,
+  type ActionContext,
   type ActionDef,
   type AuthAdapter,
   type ErrorInput,
@@ -53,6 +54,7 @@ import {
   type User,
 } from '../core/index.ts'
 import { readPackageVersion } from '../core/package-version.ts'
+import { designResponse, isDesignScenario, type DesignScenario } from '../design/index.ts'
 import { mittEvents } from '../events/drivers/mitt.ts'
 import { nodeServer, type NodeServerHandle } from '../server/drivers/node.ts'
 import { serializeResult } from '../server/index.ts'
@@ -84,6 +86,14 @@ export interface OpusDesignOptions {
    */
   entry?: string | string[]
 
+  /**
+   * Cenários de design (ADR 0037): módulos que exportam `defineDesignScenario(contrato, resposta)`.
+   * Aceita caminhos e globs, como `entry`. O cenário vence o `mockHandler` e a resposta padrão
+   * gerada pelo `fake`; cenário de action inexistente impede o boot, com a lista no erro.
+   * Sem default: o projeto decide onde os cenários ficam e se são versionados.
+   */
+  scenarios?: string | string[]
+
   /** Prefixo do path. Default '/api'. */
   apiPrefix?: string
 
@@ -145,10 +155,14 @@ const PROBE_PATH = '/__opus/design'
 // deixá-los chegar no handler (moram fora do apiPrefix).
 const RUNTIME_ENDPOINT_PATHS = new Set(['/health', '/ready', '/openapi.json'])
 
+/** De onde vem a resposta de cada action no modo design, na ordem de precedência. */
+type DesignSource = 'scenario' | 'mock' | 'handler' | 'generated'
+
 interface DesignState {
   handle: NodeServerHandle
   runtime: Runtime
   actions: ActionDef[]
+  sources: Map<string, DesignSource>
 }
 
 export function opusDesign(options: OpusDesignOptions = {}): Plugin {
@@ -156,6 +170,12 @@ export function opusDesign(options: OpusDesignOptions = {}): Plugin {
   const entries = Array.isArray(options.entry)
     ? options.entry
     : [options.entry ?? './opus.config.ts']
+  const scenarioEntries =
+    options.scenarios === undefined
+      ? []
+      : Array.isArray(options.scenarios)
+        ? options.scenarios
+        : [options.scenarios]
   const devBackend = options.devBackend === true
   // Mais-específico primeiro: prefixo mais longo vence.
   const stubEntries = Object.entries(options.stubs ?? {}).sort(
@@ -194,8 +214,8 @@ export function opusDesign(options: OpusDesignOptions = {}): Plugin {
       exProxyPrefixes = Object.keys(config.server?.proxy ?? {})
       // 2) Mata o proxy: fecha o vazamento preview→prod pra QUALQUER prefixo.
       if (config.server?.proxy !== undefined) config.server.proxy = undefined
-      // 3) O execute() roteia handler×mockHandler lendo OPUS_MODE (isOpusDesignMode);
-      //    com o runtime local, o preview fica autossuficiente.
+      // 3) O execute() roteia pro mockHandler lendo OPUS_MODE (isOpusDesignMode); o boot
+      //    liga em cada action a resposta de design, e o preview fica autossuficiente.
       process.env.OPUS_MODE = 'design'
     },
 
@@ -215,7 +235,14 @@ export function opusDesign(options: OpusDesignOptions = {}): Plugin {
             registrables.push(...(await loadEntry(server, entry)))
           }
         }
-        const { actions, dropped } = collectActions(registrables)
+        const collected = collectActions(registrables)
+        const { dropped } = collected
+        const scenarios = isDesign
+          ? await loadScenarios(server, scenarioEntries, collected.actions)
+          : new Map<string, DesignScenario>()
+        const { actions, sources } = isDesign
+          ? prepareDesignActions(collected.actions, scenarios)
+          : { actions: collected.actions, sources: new Map<string, DesignSource>() }
 
         const handle = nodeServer({ apiPrefix })
         const runtime = createRuntime({
@@ -223,8 +250,8 @@ export function opusDesign(options: OpusDesignOptions = {}): Plugin {
           auth: designAuth({ user: options.user, tenantId: options.tenantId }),
           eventBus: mittEvents(),
           storage: memStorage(),
-          // SEM `data` de propósito: design não toca ctx.db — handler real sem
-          // mock falhando é o sinal certo de que falta mockar.
+          // SEM `data` de propósito: design não toca ctx.db. Uma action ligada a handler real
+          // que dependa do banco falha aqui; o caminho é um cenário (ADR 0037).
           ...options.runtime,
           config: { env: 'development', dev: true, ...options.runtime?.config },
         })
@@ -236,19 +263,9 @@ export function opusDesign(options: OpusDesignOptions = {}): Plugin {
             `[opus-design] ${dropped} reaction(s)/schedule(s) ignorada(s) — o runtime de design é request/response.`,
           )
         }
-        if (isDesign) {
-          for (const action of actions) {
-            if (action.mockHandler === undefined) {
-              logger.warn(
-                `[opus-design] Action "${action.name}" sem mockHandler — em design cai no handler real e pode falhar sem adapters.`,
-              )
-            }
-          }
-        }
-
         await runtime.start()
         handle.adapter.mountEndpoints({ health: true, ready: true, openapi: true })
-        return { handle, runtime, actions }
+        return { handle, runtime, actions, sources }
       }
 
       // Promise-mutex: requests em voo aguardam o MESMO boot; rebuild (stale)
@@ -285,8 +302,9 @@ export function opusDesign(options: OpusDesignOptions = {}): Plugin {
       //   add/unlink: QUALQUER arquivo sob o root (fora node_modules/.git) —
       //   arquivo novo nunca importado não está no graph, e é exatamente ele
       //   que um entry glob precisa enxergar. Over-invalidation é barata.
+      const watchedEntries = [...entries, ...scenarioEntries]
       const entryPaths = new Set(
-        entries
+        watchedEntries
           .filter((entry) => !isGlobPattern(entry))
           .map((entry) => path.resolve(server.config.root, entry)),
       )
@@ -294,7 +312,7 @@ export function opusDesign(options: OpusDesignOptions = {}): Plugin {
       // pode apontar pra FORA dele (ex.: '../../services/*/contract.ts', caso GB):
       // mandamos o chokidar observar o PREFIXO ESTÁTICO de cada glob — o mesmo que
       // o expandGlob anda, nunca o mundo — pra change/unlink lá também invalidar.
-      const globSpecs = entries
+      const globSpecs = watchedEntries
         .filter(isGlobPattern)
         .map((pattern) => globSpec(server.config.root, pattern))
       for (const { prefixDir } of globSpecs) server.watcher.add(prefixDir)
@@ -341,12 +359,21 @@ export function opusDesign(options: OpusDesignOptions = {}): Plugin {
         }
         try {
           const state = await ensureBoot()
-          const unmocked = state.actions.filter((a) => a.mockHandler === undefined)
+          const named = (source: DesignSource): string[] =>
+            state.actions.filter((a) => state.sources.get(a.name) === source).map((a) => a.name)
+          const scenarios = named('scenario')
+          const mocks = named('mock')
           payload.runtime = {
             prefix: apiPrefix,
             actions: state.actions.length,
-            mocked: state.actions.length - unmocked.length,
-            unmocked: unmocked.map((a) => a.name),
+            // `mocked`/`unmocked` mantêm o formato anterior da sonda: resposta escrita à mão
+            // (cenário ou mockHandler) contra o resto, que responde por handler real ou `fake`.
+            mocked: scenarios.length + mocks.length,
+            unmocked: state.actions
+              .filter((a) => !['scenario', 'mock'].includes(state.sources.get(a.name) ?? ''))
+              .map((a) => a.name),
+            scenarios,
+            generated: named('generated'),
           }
         } catch (err) {
           payload.error = String(err)
@@ -605,6 +632,89 @@ function registrablesOfModule(mod: Record<string, unknown>): unknown[] {
   return [...out]
 }
 
+// =============================================================================
+// Dados de design (ADR 0037)
+// =============================================================================
+
+/**
+ * Carrega os cenários dos módulos casados por `scenarios`. Cenário de action inexistente ou dois
+ * cenários para a mesma action impedem o boot: o preview mostra o erro em vez de silenciar.
+ */
+async function loadScenarios(
+  server: ViteDevServer,
+  patterns: string[],
+  actions: ActionDef[],
+): Promise<Map<string, DesignScenario>> {
+  const scenarios = new Map<string, DesignScenario>()
+  const known = new Set(actions.map((action) => action.name))
+  const unknown: string[] = []
+  const duplicated: string[] = []
+  for (const pattern of patterns) {
+    const files = isGlobPattern(pattern) ? expandGlob(server.config.root, pattern) : [normalizeEntryUrl(pattern)]
+    for (const file of files) {
+      const mod = (await server.ssrLoadModule(file)) as Record<string, unknown>
+      for (const scenario of scenariosOfModule(mod)) {
+        if (!known.has(scenario.action)) unknown.push(scenario.action)
+        else if (scenarios.has(scenario.action) && scenarios.get(scenario.action) !== scenario) {
+          duplicated.push(scenario.action)
+        } else scenarios.set(scenario.action, scenario)
+      }
+    }
+  }
+  if (unknown.length > 0 || duplicated.length > 0) {
+    const names = (list: string[]): string => [...new Set(list)].join(', ')
+    const problems = [
+      unknown.length > 0 ? `sem action registrada: ${names(unknown)}` : '',
+      duplicated.length > 0 ? `mais de um cenário para: ${names(duplicated)}` : '',
+    ].filter(Boolean)
+    throw error({
+      code: 'design.invalid_scenario',
+      category: 'internal',
+      message: `Cenários de design inválidos (${problems.join('; ')}).`,
+    })
+  }
+  return scenarios
+}
+
+function scenariosOfModule(mod: Record<string, unknown>): DesignScenario[] {
+  const out = new Set<DesignScenario>()
+  const add = (value: unknown): void => {
+    if (Array.isArray(value)) value.forEach(add)
+    else if (isDesignScenario(value)) out.add(value)
+  }
+  Object.values(mod).forEach(add)
+  return [...out]
+}
+
+/**
+ * Liga a cada action a resposta de design, nesta precedência: cenário, `mockHandler` declarado,
+ * handler real (`bindAction`) e, por fim, a resposta padrão gerada pelo `fake`.
+ */
+function prepareDesignActions(
+  actions: ActionDef[],
+  scenarios: Map<string, DesignScenario>,
+): { actions: ActionDef[]; sources: Map<string, DesignSource> } {
+  const sources = new Map<string, DesignSource>()
+  const prepared = actions.map((action): ActionDef => {
+    const scenario = scenarios.get(action.name)
+    if (scenario !== undefined) {
+      sources.set(action.name, 'scenario')
+      return { ...action, mockHandler: (ctx: ActionContext, input: unknown) => scenario.respond(input, ctx) } as ActionDef
+    }
+    if (action.mockHandler !== undefined) {
+      sources.set(action.name, 'mock')
+      return action
+    }
+    if (typeof (action as { handler?: unknown }).handler === 'function') {
+      sources.set(action.name, 'handler')
+      return action
+    }
+    sources.set(action.name, 'generated')
+    return { ...action, mockHandler: async (_ctx: ActionContext, input: unknown) => designResponse(action, input) } as ActionDef
+  })
+  return { actions: prepared, sources }
+}
+
 /** Achata os registráveis em actions; reactions/schedules ficam de fora (contados). */
 function collectActions(items: unknown[]): { actions: ActionDef[]; dropped: number } {
   const actions: ActionDef[] = []
@@ -621,7 +731,7 @@ function collectActions(items: unknown[]): { actions: ActionDef[]; dropped: numb
       dropped += 1
       continue
     }
-    // ActionDef ou contrato (sem handler): em design o mockHandler responde.
+    // ActionDef ou contrato (sem handler): em design, a resposta de design responde.
     actions.push(item as ActionDef)
   }
   return { actions, dropped }