@softize/opus 22.0.0 → 22.1.0

package/CHANGELOG.md

@@ -7,6 +7,30 @@ Depois de qualquer bump, rode os gates (`typecheck` · `test` · `opus check` ·
 `opus copy --check` · `base copy check` · `manifest:check`) — eles apontam o que a
 mudança cobra do seu código.
 
+## 22.1.0 — 2026-09-28
+
+Os dados do modo design saem do contrato (ADR 0037). No modo design, toda action passa a responder
+sem que o contrato declare nada: a resposta é gerada pelo `fake` a partir do `output`, a mesma
+requisição recebe a mesma resposta, uma `list` devolve três páginas do tamanho pedido em `limit` (20
+por padrão) pela paginação declarada, e a saída repete o `id` da entrada quando o schema aceita.
+Quando o design precisa de coerência, um cenário escrito com `defineDesignScenario`, do novo
+`@softize/opus/design`, responde no lugar da resposta gerada. O plugin encontra os cenários pela
+opção `scenarios` de `opusDesign()`, com caminhos ou globs; um cenário de action inexistente, ou
+dois cenários para a mesma action, impedem o runtime de design de subir, e o erro lista os nomes.
+
+`mockHandler` fica obsoleto. Ele ainda responde no modo design, abaixo do cenário e acima da
+resposta gerada, e sai na 23.0.0. Os tipos o marcam com `@deprecated`. O `opus check` passa a
+contar, numa linha de aviso que não reprova, quantas actions ainda o declaram. A sonda
+`/__opus/design` ganha `scenarios` e `generated`; `mocked` e `unmocked` mantêm o formato anterior.
+
+O template de `opus create` e as skills `create-opus-action` e `test-opus-action` deixam de ensinar
+`mockHandler`.
+
+**O que fazer:** nada é obrigatório nesta versão. Para migrar, apague os `mockHandler` dos
+contratos; se a resposta de algum importar para o design, transforme-a em cenário e aponte a opção
+`scenarios` do plugin para o lugar onde os cenários ficam. Testes que usavam `runAction` com
+`OPUS_MODE=design` para exercitar o mock devem testar a action ligada ao handler.
+
 ## 22.0.0 — 2026-09-28
 
 As superfícies passam a usar uma introdução única e ganham composições explícitas para conteúdo

package/bin/cli.mjs

@@ -40,7 +40,15 @@ async function cmdCheck(dir) {
     for (const error of materialization.errors) log('error', `✗ opus check: ${error}`)
     process.exit(1)
   }
-  const { files, actions, contracts, findings, hasMarker } = await scanDir(root)
+  const { files, actions, contracts, deprecatedMockHandlers, findings, hasMarker } = await scanDir(root)
+  // Aviso de migração, não violação: uma linha só, para não poluir o gate a cada execução.
+  if (deprecatedMockHandlers > 0) {
+    log(
+      'warn',
+      `⚠ opus check: ${deprecatedMockHandlers} action(s) ainda declaram \`mockHandler\`, que sai na próxima major. ` +
+        'No modo design, a action sem mock já responde com dado gerado; use `defineDesignScenario` quando o design precisar de um cenário (ADR 0037).',
+    )
+  }
 
   if (actions === 0 && findings.length === 0) {
     const verdict = emptyScanVerdict({ hasMarker, contracts })

package/bin/lib/check.mjs

@@ -642,6 +642,8 @@ export function checkProject(sources) {
   const productDeclarations = [];
   const entityNames = new Set();
   const actionNames = new Set();
+  // `mockHandler` obsoleto (ADR 0037): contado, não reprovado — a minor ainda o aceita.
+  let deprecatedMockHandlers = 0;
 
   for (const { file, text } of sources) {
     const declarations = parseDataProducts(file, text);
@@ -666,6 +668,7 @@ export function checkProject(sources) {
         if (item.name !== null) actionNames.add(item.name);
       }
       for (const f of lintAction(item)) findings.push({ ...f, file });
+      if (item.keys.includes("mockHandler")) deprecatedMockHandlers += 1;
     }
   }
 
@@ -771,6 +774,7 @@ export function checkProject(sources) {
     actions,
     contracts,
     dataProducts: productDeclarations.length,
+    deprecatedMockHandlers,
     findings,
   };
 }
@@ -1921,7 +1925,7 @@ async function walkUiFiles(dir, acc = []) {
   return acc;
 }
 
-/** Escaneia um diretório → { files, actions, contracts, findings, hasMarker }.
+/** Escaneia um diretório → { files, actions, contracts, deprecatedMockHandlers, findings, hasMarker }.
  *  `hasMarker` = o diretório é um projeto opus (tem opus.json na raiz). */
 export async function scanDir(rootDir) {
   rootDir = canonicalProjectDirectory(rootDir);
@@ -1951,6 +1955,7 @@ export async function scanDir(rootDir) {
     actions: checked.actions,
     contracts: checked.contracts,
     dataProducts: checked.dataProducts,
+    deprecatedMockHandlers: checked.deprecatedMockHandlers,
     findings: [...checked.findings, ...uiFindings],
     hasMarker,
   };

package/docs/adr/0037-design-data-lives-outside-the-contract.md

@@ -0,0 +1,117 @@
+# ADR 0037 — Dados do modo design ficam fora do contrato
+
+- **Status:** aceita; a primeira etapa saiu na 22.1.0, e a remoção fica para a 23.0.0.
+- **Data:** 2026-09-28.
+- **Relacionadas:** ADR 0002 (seeds estruturados).
+
+## Contexto
+
+O modo design serve para desenhar e revisar telas sem backend: `opusDesign()` monta o runtime
+dentro do dev server, e cada action responde pelo `mockHandler` declarado no contrato. O preview de
+sessão do Maestro depende desse modo e não tem outro propósito além de design.
+
+Em setembro de 2026, o único consumidor, a Grand Brasil, tinha 233 `mockHandler` para 256
+contratos, cerca de 3.200 linhas entre handlers, fixtures e estado simulado. A medição mostrou três
+problemas:
+
+- **O mock viaja com o contrato.** O contrato é a fatia compartilhada com a interface, então o
+  build de produção da aplicação leva os handlers simulados e suas fixtures. Um build de produção
+  da Grand Brasil continha textos das fixtures e os próprios handlers.
+- **Metade dos mocks não acrescenta nada ao schema.** Cerca de 110 handlers devolvem um literal
+  fixo (`{ id: 'mock-x' }`) ou uma lista vazia, o que o `fake` já gera a partir do `output`.
+- **A outra metade replica o domínio.** Cerca de 95 handlers simulam um CRUD em memória e
+  reimplementam regras do handler real, como o significado de cada filtro operacional de uma
+  listagem. Em setembro, 19 commits de funcionalidade tiveram de alterar mocks junto com o código
+  real, e nada garante que as duas versões da regra continuem iguais.
+
+Forças em tensão:
+
+- a aplicação real deve carregar o mínimo possível de algo que só existe para design;
+- o preview precisa responder a qualquer action, inclusive às criadas durante a sessão;
+- às vezes o design precisa de coerência entre respostas, como um item em cada situação ou algo
+  criado que aparece na lista em seguida;
+- no preview, variar entre sessões é aceitável, porque dado de design não é evidência. Os seeds da
+  ADR 0002 são evidência e continuam determinísticos;
+- o Opus é protocolo e SDK: onde os cenários ficam e se são versionados é escolha do projeto.
+
+## Decisão
+
+1. **O contrato deixa de declarar dados de design.** `mockHandler` sai de `ActionBase`, do
+   contrato, do `ActionDef` e do `runAction`. O runtime de produção não lê mais `OPUS_MODE` nem
+   tem ramo de design. Toda a lógica de design fica em `@softize/opus/vite`.
+2. **Toda action responde por padrão no modo design.** O plugin registra cada contrato com um
+   executor de design que, na ausência de cenário, devolve dado gerado pelo `fake` a partir do
+   `output`:
+   - `list` devolve três páginas geradas por `fakeMany`, com `items`, `cursor` e `total`, 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, porque sobre dado
+     sorteado o resultado não mostraria nada útil; quando o filtro importar para o design, o
+     caminho é um cenário;
+   - a semente é derivada do nome da action e da entrada canônica, então a mesma requisição recebe
+     a mesma resposta;
+   - quando a entrada e a saída têm `id`, a saída ecoa o `id` da entrada, desde que o schema da
+     saída aceite esse valor, para que abrir um item listado mostre o mesmo identificador;
+   - uma action ligada a um handler real (`bindAction`) mantém esse handler, como hoje.
+3. **Cenários são registrados fora do contrato, pelo nome da action.** O plugin ganha a opção
+   `scenarios`, com um ou mais globs. Os módulos casados exportam cenários criados por
+   `defineDesignScenario(contrato, resposta)`, e a resposta pode ser um valor ou uma função tipada
+   pela entrada e pela saída do contrato. O cenário vence a resposta padrão. Um cenário para uma
+   action inexistente é erro visível no preview, não um silêncio.
+4. **O Opus não decide onde os cenários ficam.** A opção não tem default dentro do código da
+   aplicação. O consumidor escolhe, por exemplo, uma pasta ignorada pelo git que o agente da sessão
+   preenche sob demanda. Cenários começam descartáveis: só vale discutir versionar um cenário no
+   repositório do consumidor quando o mesmo for recriado em sessões diferentes.
+5. **Stubs de rotas externas continuam como estão.** A opção `stubs` segue atendendo superfícies
+   fora do protocolo de actions, como autenticação e motores externos.
+
+## Consequências
+
+- A aplicação deixa de carregar mocks. O contrato volta a descrever só a capacidade, e o build de
+  produção não inclui dados de design.
+- Uma action nova aparece no preview sem nenhuma linha de mock.
+- O dado padrão tem o formato certo, mas não a regra de negócio: valores de enum são sorteados, e
+  campos de uma listagem e de um detalhe só coincidem no `id`. Quando isso atrapalhar o design, o
+  caminho é um cenário.
+- Sem cenário, não há estado entre chamadas: criar um item não o faz aparecer na lista.
+- É uma versão major. Quem declara `mockHandler` precisa remover a declaração ou transformá-la em
+  cenário, e testes que usam `OPUS_MODE=design` com `runAction` precisam de outra forma de
+  exercitar o contrato.
+- O template de `opus create`, a documentação "Prototipar com dados simulados", as skills
+  `create-opus-action` e `test-opus-action` e o gate de ordem de campos (`check.mjs`) mudam junto.
+- No Maestro, que fica fora deste pacote, o preview continua igual. O agente da sessão passa a
+  escrever cenários quando precisar, orientado por uma skill própria.
+
+## Alternativas descartadas
+
+- **Manter o estado atual.** Preserva cenários prontos entre sessões, mas mantém o mock no bundle,
+  a regra de negócio duplicada e o custo de cada funcionalidade nova.
+- **Remover `mockHandler` apenas no build de produção.** Resolve o bundle e nada mais. O contrato
+  continua misturando capacidade e simulação, e a duplicação de regra permanece.
+- **Preview com backend real e dados dos seeds.** Mostra o comportamento verdadeiro e elimina os
+  mocks, mas exige banco, API e isolamento por sessão num preview que só serve a design, além de
+  rever as decisões do Maestro de manter o preview isolado e sem Postgres.
+- **CRUD em memória genérico a partir de metadado novo no contrato.** Exigiria declarar entidade e
+  operação em cada action e, mesmo assim, não cobriria regras de negócio, que continuariam
+  escritas à mão.
+- **Somente a resposta padrão, sem cenários.** É o mínimo absoluto, mas deixaria o design sem saída
+  quando a coerência importa. O custo do mecanismo de cenários é pequeno perto disso.
+
+## Transição
+
+A saída acontece em duas versões. A 22.1.0 adiciona a resposta padrão e os cenários, com
+`mockHandler` ainda aceito e precedendo a resposta gerada, e o `check` passa a contar o campo como
+obsoleto. O consumidor remove seus mocks domínio a domínio. A 23.0.0 remove o campo e o ramo de
+design do runtime.
+
+## Verificação
+
+- testes do plugin: resposta padrão por `kind` (`view`, `list`, `form`, `simple`), páginas do
+  tamanho pedido em `limit` com a paginação declarada, mesma resposta para a mesma entrada, eco do
+  `id`, precedência do cenário e erro para cenário sem action ou duplicado;
+- teste de tipos: `defineDesignScenario` infere entrada e saída do contrato e rejeita resposta
+  incompatível;
+- busca estática: nenhum `OPUS_MODE` nem `mockHandler` em `src/core` e `src/testing` depois da
+  major;
+- no consumidor: nenhum `mockHandler` nos contratos, e o build de produção sem textos das fixtures
+  antigas;
+- typecheck, suíte do pacote, `opus check` e os gates de materialização verdes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softize/opus",
-  "version": "22.0.0",
+  "version": "22.1.0",
   "description": "End-to-end action protocol for TypeScript. Single package with subpath exports (core + adapters).",
   "license": "MIT",
   "type": "module",
@@ -173,6 +173,10 @@
       "types": "./src/seed/index.ts",
       "default": "./src/seed/index.ts"
     },
+    "./design": {
+      "types": "./src/design/index.ts",
+      "default": "./src/design/index.ts"
+    },
     "./presentation": {
       "types": "./src/presentation/index.ts",
       "default": "./src/presentation/index.ts"

package/registry/skills/create-opus-action/references/contract-and-binding.md

@@ -1,12 +1,14 @@
 # Contrato e binding
 
-O contrato contém `name`, `kind`, documentação, schemas, metadata de UI, autorização
-declarativa compartilhável e `mockHandler` de design quando aplicável.
+O contrato contém `name`, `kind`, documentação, schemas, metadata de UI e autorização
+declarativa compartilhável. Ele não declara dados de design: no modo design, a action sem mock já
+responde com dado gerado a partir do `output`, e um cenário específico, quando necessário, fica
+fora do contrato em `defineDesignScenario` (ADR 0037). `mockHandler` está obsoleto.
 
 O binding contém `handler`, `loads`, autorização dependente de dados carregados, execução
 em background, eventos e idempotência. `bindAction(contract, binding)` produz o `ActionDef`
 registrado no runtime.
 
 Ordem cobrada pelo check: identidade → documentação → input/output → autorização →
-handler/mock → comportamento. Campos específicos do kind permanecem junto do grupo ao qual
+handler → comportamento. Campos específicos do kind permanecem junto do grupo ao qual
 servem e o scaffold acompanha a forma atual do SDK.

package/registry/skills/create-opus-action/scripts/scaffold.mjs

@@ -18,7 +18,6 @@ ${common}
   input: z.object({}),
   output: z.object({ id: z.string() }),
   paginate: 'cursor',
-  mockHandler: async () => ({ items: [], cursor: { next: null }, total: 0 }),
 })`
   }
   if (kind === 'form') {
@@ -30,7 +29,6 @@ ${common}
   input: z.object({ id: z.string() }),
   output: z.object({ id: z.string() }),
   fields: { id: { label: 'Identificador' } },
-  mockHandler: async (_ctx, input) => ({ id: input.id }),
 })`
   }
   if (kind === 'view') {
@@ -40,7 +38,6 @@ ${common}
   description: 'Descreva o comportamento de negócio e seus limites.',
   input: z.object({ id: z.string() }),
   output: z.object({ id: z.string() }),
-  mockHandler: async (_ctx, input) => ({ id: input.id }),
 })`
   }
   return `export const ${identifier} = defineContract({
@@ -50,7 +47,6 @@ ${common}
   messages: { success: 'Operação concluída.', error: 'Não foi possível concluir.' },
   input: z.object({ id: z.string() }),
   output: z.object({ ok: z.boolean() }),
-  mockHandler: async () => ({ ok: true }),
 })`
 }
 

package/registry/skills/test-opus-action/SKILL.md

@@ -12,8 +12,8 @@ infraestrutura real quando a unidade é o contrato.
 
 ## Procedimento
 
-1. Importar o `ActionDef` produzido pelo binding; para contrato puro, testar `mockHandler`
-   apenas no modo design.
+1. Importar o `ActionDef` produzido pelo binding. Dados do modo design não são comportamento da
+   action e não entram nestes testes.
 2. Executar com `runAction` e fornecer `user`, `can`, `loaded`, storage ou outros adapters
    pelas opções do harness.
 3. Cobrir sucesso, input inválido, autorização negada e erros de negócio materiais.

package/registry/skills/test-opus-action/references/harness.md

@@ -6,5 +6,5 @@
 - `memStorage()`: adapter de storage em memória com inspeção de chaves.
 - `fake` e `fakeMany`: dados determinísticos derivados de schema.
 
-Prefira o binding completo em testes de execução. Um contrato sem handler só executa via
-`mockHandler` quando `OPUS_MODE=design`.
+Teste o binding completo. Um contrato sem handler falha com `testing.no_handler`: os dados do modo
+design são gerados pelo plugin `opusDesign()` e não são comportamento da action.

package/registry/templates/app/src/App.tsx

@@ -9,7 +9,7 @@ type TaskItem = z.infer<typeof Task>
 export function App(): React.ReactElement {
   // O front consome o CONTRATO via /api — o plugin opusDesign (vite.config.ts)
   // serve o backend no próprio dev server: dev normal executa o handler real;
-  // `pnpm dev:design` responde com o mockHandler, isolado de qualquer backend.
+  // `pnpm dev:design` responde com dado gerado a partir do contrato, isolado de qualquer backend.
   const { items, isLoading, error, refetch } = useListAction<TaskItem>(taskList)
 
   return (

package/registry/templates/app/src/domains/tasks/actions/list.test.ts

@@ -1,6 +1,6 @@
-import { afterEach, describe, expect, it } from 'vitest'
+import { describe, expect, it } from 'vitest'
 import { runAction } from '@softize/opus/testing'
-import { Task, taskList, taskListImpl } from './list.ts'
+import { taskListImpl } from './list.ts'
 
 // O harness roda o MESMO pipeline do runtime (valida input, cobra auth, valida
 // output) — teste pelo contrato, não chamando o handler à mão.
@@ -14,21 +14,4 @@ describe('task.list', () => {
   it('sem usuário, barra: a action não é pública', async () => {
     await expect(runAction(taskListImpl, {})).rejects.toMatchObject({ code: 'auth.unauthenticated' })
   })
-
-  describe('modo design (o que o `pnpm dev:design` serve)', () => {
-    afterEach(() => {
-      // OPUS_MODE é global do processo — limpa pra não vazar entre testes.
-      delete process.env['OPUS_MODE']
-    })
-
-    it('o contrato puro responde pelo mockHandler, com dado válido pro schema', async () => {
-      process.env['OPUS_MODE'] = 'design'
-      const { output } = await runAction(taskList, {}, { user: { id: 'u1' } })
-      expect(output.items.length).toBeGreaterThan(0)
-      // `list` pula a validação de output no pipeline — afirme item a item.
-      for (const item of output.items) {
-        expect(Task.safeParse(item).success).toBe(true)
-      }
-    })
-  })
 })

package/registry/templates/app/src/domains/tasks/actions/list.ts

@@ -1,14 +1,13 @@
 import { z } from 'zod'
 import { bindAction, defineContract } from '@softize/opus/core'
-import { fakeMany } from '@softize/opus/testing'
 
-/** Item do domínio-exemplo — o schema alimenta contrato, mock e testes. */
+/** Item do domínio-exemplo — o schema alimenta contrato, dados de design e testes. */
 export const Task = z.object({ id: z.string(), title: z.string(), done: z.boolean() })
 
 // O split canônico contrato↔handler: o CONTRATO é declarativo e roda nos dois
 // lados (a SPA consome via useListAction); o BINDING é server-only. Em
-// `pnpm dev:design` o mockHandler responde (dado fake do próprio schema);
-// no dev normal e em prod, o handler real do binding assume.
+// `pnpm dev:design` o plugin responde com dado gerado a partir do `output`
+// (ADR 0037); no dev normal e em prod, o handler real do binding assume.
 export const taskList = defineContract({
   name: 'task.list',
   kind: 'list',
@@ -19,7 +18,6 @@ export const taskList = defineContract({
   input: z.object({}),
   output: Task,
   paginate: 'cursor',
-  mockHandler: async () => ({ items: fakeMany(Task, 5), cursor: { next: null }, total: 5 }),
 })
 
 // Fixture em memória — o domínio-exemplo não tem banco; troque pelo seu repositório.

package/registry/templates/app/vite.config.ts

@@ -5,11 +5,12 @@ import { fileURLToPath } from 'node:url'
 
 /**
  * Modo design (`vite --mode design`, script dev:design): o runtime Opus sobe DENTRO do
- * dev server e os mockHandler dos contratos respondem o `/api` — preview autossuficiente,
+ * dev server e as actions respondem o `/api` com dado gerado a partir do `output` do contrato
+ * (ADR 0037; cenários específicos entram pela opção `scenarios`) — preview autossuficiente,
  * isolado de prod (o plugin desliga o `server.proxy` sozinho; prefixo ex-proxy sem
  * cobertura responde 503, nunca vaza pra porta real). Quando o app ganhar um backend real,
  * o `dev` normal proxeia pra ele (adicione `server.proxy`); o preview de design segue nos
- * mocks. O entry default do plugin é `./opus.config.ts` (a fonte da spec deste app).
+ * dados de design. O entry default do plugin é `./opus.config.ts` (a fonte da spec deste app).
  *
  * Import DINÂMICO NO TOP-LEVEL, de propósito, e em duas condições que andam juntas: (1) o
  * @softize/opus embarca TS source e o config loader padrão (esbuild bundle — o que build e

package/src/core/domain.ts

@@ -36,7 +36,7 @@ import type { ActionDef, ReactionDef, ScheduleDef } from './types.ts'
  * Um registrável de action num domínio: BOUND (`ActionDef`, com handler) ou
  * contrato PURO (`ActionContract`, sem handler). Um domínio de design — a
  * fatia isomorfa (ADR 0004) — registra só contratos, e em modo design o
- * `mockHandler` responde. Fora de design, contrato sem handler falha no
+ * plugin `opusDesign()` responde por eles (ADR 0037). Fora de design, contrato sem handler falha no
  * `execute` (comportamento INTENCIONAL); o tipo só deixa de exigir o cast.
  */
 export type DomainAction = ActionDef | ActionContract
@@ -205,7 +205,7 @@ function* iterateActions(
 ): IterableIterator<ActionDef> {
   if (actions === undefined) return
   // Um contrato puro (`ActionContract`, sem handler) entra como `ActionDef` no
-  // runtime — em design o `mockHandler` responde; fora de design, a ausência de
+  // runtime — em design o plugin `opusDesign()` responde; fora de design, a ausência de
   // handler falha no `execute` (intencional). O cast reconcilia o tipo neste
   // boundary de normalização; ver `DomainAction`.
   if (Array.isArray(actions)) {

package/src/core/types.ts

@@ -821,27 +821,11 @@ export interface ActionBase<In, Out, ParsedIn = In> {
 
   /**
    * Handler alternativo executado quando `process.env.OPUS_MODE === 'design'`.
-   * Use pra prototipar UI com dados realistas sem precisar do backend pronto.
    *
-   * Em modo design: runtime tenta `mockHandler` primeiro; se ausente, cai
-   * no `handler` normal (permitindo testar pontualmente real ao lado de
-   * mocks).
-   *
-   * Em modo default (sem env): `mockHandler` é ignorado. Útil pra apagar
-   * em revisão ou manter pro Designer reusar.
-   *
-   * Pattern recomendado pra ações que só têm mock durante dev:
-   *
-   * ```ts
-   * defineAction({
-   *   name: 'ticket.list',
-   *   // ...
-   *   mockHandler: async () => MOCK_TICKETS,
-   *   handler: () => {
-   *     throw new Error('handler real ainda não implementado — use OPUS_MODE=design')
-   *   },
-   * })
-   * ```
+   * @deprecated Desde a 22.1.0 (ADR 0037); sai na próxima major. No modo design, a action sem
+   * mock já responde com dado gerado a partir do `output`; quando o design precisar de uma resposta
+   * específica, declare um cenário fora do contrato com `defineDesignScenario`, de
+   * `@softize/opus/design`, e aponte a opção `scenarios` do `opusDesign()` para ele.
    */
   mockHandler?: HandlerFn<ParsedIn, Out>
 
@@ -919,6 +903,8 @@ export interface ListAction<In, Out, ParsedIn = In>
   /**
    * Mesma semântica de `ActionBase.mockHandler`, mas devolve `Paginated<Out>`
    * (search retorna lista paginada, não item solto).
+   *
+   * @deprecated Desde a 22.1.0 (ADR 0037); ver `ActionBase.mockHandler`.
    */
   mockHandler?: (
     ctx: ActionContext,

package/src/design/index.ts

@@ -0,0 +1,179 @@
+/**
+ * Dados do modo design fora do contrato (ADR 0037).
+ *
+ * No modo design, toda action responde: sem cenário, a resposta é gerada pelo `fake` a partir do
+ * `output` do contrato. Quando o design precisa de coerência (um item em cada situação, algo criado
+ * que aparece na lista), um cenário registrado pelo nome da action vence a resposta padrão.
+ *
+ * O módulo é isomórfico e não conhece Vite: o plugin `opusDesign()` carrega os cenários e liga as
+ * respostas ao runtime de design.
+ */
+
+import { z } from 'zod'
+import type { ActionContext, InferOutput, Paginated } from '../core/types.ts'
+import { fake, fakeMany } from '../testing/fake.ts'
+
+// =============================================================================
+// Cenários
+// =============================================================================
+
+// `Symbol.for`: o plugin roda no processo do Vite e carrega os cenários pelo pipeline SSR, então
+// a marca precisa sobreviver a duas instâncias do módulo.
+const SCENARIO = Symbol.for('@softize/opus/design-scenario')
+
+type ContractKind = 'simple' | 'form' | 'list' | 'view'
+
+interface ScenarioContract {
+  name: string
+  kind: ContractKind
+  input: unknown
+  output: unknown
+}
+
+type ScenarioInput<C> = C extends { input: infer S } ? InferOutput<S> : never
+
+type ScenarioOutput<C> = C extends { output: infer S }
+  ? C extends { kind: 'list' }
+    ? Paginated<InferOutput<S>>
+    : InferOutput<S>
+  : never
+
+/** Resposta de um cenário: o valor devolvido, ou uma função da entrada já validada. */
+export type DesignScenarioResponse<C> =
+  | ScenarioOutput<C>
+  | ((input: ScenarioInput<C>, ctx: ActionContext) => ScenarioOutput<C> | Promise<ScenarioOutput<C>>)
+
+/** Cenário de design ligado a uma action pelo nome. */
+export interface DesignScenario {
+  readonly [SCENARIO]: true
+  readonly action: string
+  respond(input: unknown, ctx: ActionContext): Promise<unknown>
+}
+
+/**
+ * Declara a resposta de uma action no modo design, fora do contrato. A resposta é tipada pela
+ * entrada e pela saída do contrato; em `list`, é a página completa (`items`, `cursor`, `total`).
+ */
+export function defineDesignScenario<C extends ScenarioContract>(
+  contract: C,
+  // NoInfer: o contrato é inferido só do primeiro argumento. Sem isso, a resposta entra na
+  // inferência e os literais do retorno de uma função alargam (`'closed'` vira `string`).
+  response: NoInfer<DesignScenarioResponse<C>>,
+): DesignScenario {
+  const respond =
+    typeof response === 'function'
+      ? async (input: unknown, ctx: ActionContext): Promise<unknown> =>
+          (response as (input: unknown, ctx: ActionContext) => unknown)(input, ctx)
+      : async (): Promise<unknown> => response
+  return { [SCENARIO]: true, action: contract.name, respond }
+}
+
+/** `true` quando o valor foi criado por `defineDesignScenario`. */
+export function isDesignScenario(value: unknown): value is DesignScenario {
+  return typeof value === 'object' && value !== null && (value as Record<symbol, unknown>)[SCENARIO] === true
+}
+
+// =============================================================================
+// Resposta padrão
+// =============================================================================
+
+/** Itens por página da listagem padrão quando a entrada não pede `limit`. */
+export const DESIGN_PAGE_SIZE = 20
+
+// Teto do `limit` atendido: o maior tamanho de página que o `ActionList` oferece.
+const DESIGN_MAX_PAGE_SIZE = 100
+
+// Três páginas: o bastante para a paginação do preview ter para onde ir.
+const DESIGN_PAGES = 3
+
+const PAGINATION_KEYS = new Set(['page', 'cursor', 'offset', 'limit'])
+
+interface DesignActionShape {
+  name: string
+  kind: ContractKind
+  output?: unknown
+  paginate?: 'cursor' | 'offset' | false
+}
+
+/**
+ * Resposta padrão do modo design: dado gerado pelo `fake` a partir do `output`, com semente
+ * derivada do nome da action e da entrada. A mesma requisição recebe a mesma resposta.
+ *
+ * - `list` devolve três páginas do tamanho pedido em `limit` ({@link DESIGN_PAGE_SIZE} quando a
+ *   entrada não pede) e respeita a paginação declarada; busca e filtros não filtram o dado gerado.
+ * - Nas demais, a saída ecoa o `id` da entrada quando o schema da saída aceita esse valor.
+ * - Saída que não é schema zod não tem gerador: a resposta é `null`.
+ */
+export function designResponse(action: DesignActionShape, input: unknown): unknown {
+  const output = action.output
+  if (!(output instanceof z.ZodType)) return null
+  const seed = `${action.name}:${canonicalJson(withoutPagination(input))}`
+
+  if (action.kind === 'list') {
+    const paginate = action.paginate ?? 'cursor'
+    const size = pageSize(input)
+    if (paginate === false) {
+      return { items: fakeMany(output, size, { seed }), cursor: { next: null }, total: size }
+    }
+    // O `limit` fica fora da semente: mudar o tamanho da página redistribui os mesmos itens.
+    const all = fakeMany(output, size * DESIGN_PAGES, { seed })
+    const page = requestedPage(input, size)
+    const start = (page - 1) * size
+    const next = paginate === 'cursor' && page < DESIGN_PAGES ? `design:${page + 1}` : null
+    const prev = paginate === 'cursor' && page > 1 ? `design:${page - 1}` : null
+    return {
+      items: all.slice(start, start + size),
+      cursor: { next, prev },
+      total: all.length,
+    } satisfies Paginated<unknown>
+  }
+
+  const value = fake(output, { seed })
+  const inputId = isRecord(input) ? input.id : undefined
+  if (inputId !== undefined && isRecord(value) && 'id' in value) {
+    // Só ecoa quando a saída continua válida: `id` numérico ou uuid na saída não aceita qualquer
+    // valor da entrada, e a validação de output do runtime recusaria a resposta.
+    const echoed = { ...value, id: inputId }
+    if (output.safeParse(echoed).success) return echoed
+  }
+  return value
+}
+
+function pageSize(input: unknown): number {
+  const limit = isRecord(input) && typeof input.limit === 'number' ? Math.trunc(input.limit) : DESIGN_PAGE_SIZE
+  return Math.min(Math.max(1, limit), DESIGN_MAX_PAGE_SIZE)
+}
+
+/** Página pedida, de 1 em diante; além da última página, a lista vem vazia. */
+function requestedPage(input: unknown, size: number): number {
+  if (!isRecord(input)) return 1
+  const cursor = typeof input.cursor === 'string' ? /^design:(\d+)$/.exec(input.cursor) : null
+  const fromCursor = cursor === null ? undefined : Number(cursor[1])
+  const fromOffset = typeof input.offset === 'number' ? Math.floor(input.offset / size) + 1 : undefined
+  const fromPage = typeof input.page === 'number' ? input.page : undefined
+  return Math.max(1, Math.trunc(fromCursor ?? fromPage ?? fromOffset ?? 1))
+}
+
+function withoutPagination(input: unknown): unknown {
+  if (!isRecord(input)) return input
+  return Object.fromEntries(Object.entries(input).filter(([key]) => !PAGINATION_KEYS.has(key)))
+}
+
+/** JSON com chaves ordenadas: a mesma entrada produz a mesma semente, qualquer que seja a ordem. */
+function canonicalJson(value: unknown): string {
+  if (typeof value === 'bigint') return `${value}n`
+  if (value instanceof Date) return JSON.stringify(value.toISOString())
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`
+  if (isRecord(value)) {
+    const entries = Object.keys(value)
+      .filter((key) => value[key] !== undefined)
+      .sort()
+      .map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`)
+    return `{${entries.join(',')}}`
+  }
+  return JSON.stringify(value) ?? 'null'
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}

package/src/testing/fake.ts

@@ -1,7 +1,7 @@
 /**
  * `fake` — dado sintético DETERMINÍSTICO a partir de um schema zod. É a matéria-prima do
- * modo design: um `mockHandler` devolve `fake(entity)`/`fakeMany(entity, n)` e o preview mostra
- * a UI com dado realista, sem backend nem banco (o design-mode do runtime nem toca `ctx.db`).
+ * modo design: a resposta gerada pelo plugin `opusDesign()` (ADR 0037) sai de `fake`/`fakeMany`
+ * sobre o `output` do contrato, e o preview mostra a UI com dado realista, sem backend nem banco.
  *
  * DETERMINISMO: PRNG próprio semeado (mulberry32) — mesma `seed` → mesma saída, sempre. Nunca
  * `Math.random` (o preview tem que ser reproduzível entre execuções). O default é semeado por

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

@@ -152,54 +152,62 @@ A autorização é fechada por padrão: sem `public: true`, a action exige usuá
 
 ## 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).
 
-`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`:
+- 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.
+
+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 +241,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/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 }