@softize/opus 22.0.0 → 22.2.0

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',
@@ -18,8 +17,9 @@ export const taskList = defineContract({
     'canônico de uma action list — contrato separado do handler, paginação por cursor.',
   input: z.object({}),
   output: Task,
+  // Leitura pelo GET (ADR 0041): list não declara `effect`. Tarefas não identificam pessoas.
+  personalData: false,
   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/action-nature.ts

@@ -0,0 +1,40 @@
+/**
+ * A natureza declarada de uma action (ADR 0041): o efeito sobre o estado e a exposição de dado
+ * pessoal. Funções puras, compartilhadas pelo runtime (registro, auditoria e ferramentas de IA) e
+ * por quem projeta o contrato.
+ */
+
+import type { ActionEffect, ActionKind } from './types.ts'
+
+/** `list` e `view` são servidas por `GET`: leitura pelo protocolo, sem declaração. */
+const READ_BY_PROTOCOL: ReadonlySet<ActionKind> = new Set(['list', 'view'])
+
+/**
+ * O efeito da action, com `list` e `view` resolvidos como leitura. `undefined` quando uma
+ * `simple` ou `form` não declarou: quem consome decide o que fazer com a ausência.
+ */
+export function resolveActionEffect(action: { kind: ActionKind; effect?: ActionEffect }): ActionEffect | undefined {
+  return READ_BY_PROTOCOL.has(action.kind) ? 'read' : action.effect
+}
+
+/** A declaração contraditória que o registro recusa: `write` numa action servida por `GET`. */
+export function hasInvalidEffect(action: { kind: ActionKind; effect?: ActionEffect }): boolean {
+  return READ_BY_PROTOCOL.has(action.kind) && action.effect === 'write'
+}
+
+/**
+ * Quantos registros a saída devolveu: os itens da página de uma `list`, os elementos de um array,
+ * 1 para um objeto e 0 para ausência. `null` quando a forma não permite contar. Só a `list` lê
+ * `items`: numa `view`, `items` é parte do registro (as linhas de um pedido, os contatos de um
+ * cliente), e o registro devolvido continua sendo um.
+ */
+export function countReturnedRecords(kind: ActionKind, output: unknown): number | null {
+  if (output === null || output === undefined) return 0
+  if (Array.isArray(output)) return output.length
+  if (typeof output === 'object') {
+    const items = (output as { items?: unknown }).items
+    if (kind === 'list' && Array.isArray(items)) return items.length
+    return 1
+  }
+  return null
+}

package/src/core/audit.ts

@@ -41,7 +41,8 @@ export class AuditEmitter {
 
   /**
    * Emite um record pros sinks apropriados.
-   * - `config === false` → no-op (audit desabilitado pra esta action).
+   * - `config === false` → no-op (audit desabilitado pra esta action), exceto quando o record
+   *   marca exposição de dado pessoal: aí sai um registro mínimo, sem input nem output (ADR 0041).
    * - `config === true | undefined` → record bruto, todos os sinks.
    * - `config: AuditConfig` → aplica redact/fields/severity/sink filter.
    *
@@ -53,11 +54,18 @@ export class AuditEmitter {
     record: AuditRecord,
     config?: boolean | AuditConfig,
   ): Promise<void> {
-    if (config === false) return
+    if (config === false) {
+      // ADR 0041: a exposição de dado pessoal é registrada mesmo com o audit desligado. O registro
+      // mínimo não leva entrada nem saída, só quem executou, a action e a contagem.
+      if (record.personalData === undefined) return
+      const { output: _output, ...rest } = record
+      return this.dispatch({ ...rest, input: null, meta: { ...record.meta, exposureOnly: true } }, this.sinks)
+    }
 
-    const processed = this.applyConfig(record, config)
-    const targetSinks = this.filterSinks(config)
+    return this.dispatch(this.applyConfig(record, config), this.filterSinks(config))
+  }
 
+  private async dispatch(processed: AuditRecord, targetSinks: AuditSink[]): Promise<void> {
     if (targetSinks.length === 0) return
 
     const results = await Promise.allSettled(

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/index.ts

@@ -67,6 +67,7 @@ export type {
   ExpandSpec,
   // action union + variants
   ActionKind,
+  ActionEffect,
   ActionBase,
   SimpleAction,
   FormAction,
@@ -222,3 +223,4 @@ export type {
   RuntimeSetupConfig,
   ResolvedRuntimeConfig,
 } from './runtime.ts'
+export { countReturnedRecords, hasInvalidEffect, resolveActionEffect } from './action-nature.ts'

package/src/core/runtime.ts

@@ -18,6 +18,7 @@ import { collectDomainWarnings, flattenDomain, isDomainConfig } from './domain.t
 import type { DomainConfig } from './domain.ts'
 import type { DataProductConfig } from './data-product.ts'
 import { AuditEmitter } from './audit.ts'
+import { countReturnedRecords, hasInvalidEffect, resolveActionEffect } from './action-nature.ts'
 import { error, isActionError, normalizeError } from './errors.ts'
 import { normalizeTraceContext } from './trace.ts'
 import { evalExpression } from '../dsl/eval.ts'
@@ -463,6 +464,15 @@ export class Runtime {
           message: `Action "${action.name}" registrada duas vezes`,
         })
       }
+      if (hasInvalidEffect(action)) {
+        throw error({
+          code: 'runtime.invalid_action_effect',
+          category: 'internal',
+          message:
+            `A action "${action.name}" é ${action.kind}, servida por GET, e não pode declarar effect: 'write'. ` +
+            'Use simple ou form para escrever (ADR 0041).',
+        })
+      }
       this.actions.set(action.name, action)
       if (this.config.dev) this.warnIgnoredExecutionFields(action)
     }
@@ -727,7 +737,11 @@ export class Runtime {
         kind: 'action',
         resultKind: 'action-result',
         ...(ctxBase.trace !== undefined ? { parent: ctxBase.trace } : {}),
-        attributes: { 'opus.action.id': actionId, 'opus.action.kind': action.kind },
+        attributes: {
+          'opus.action.id': actionId,
+          'opus.action.kind': action.kind,
+          ...natureAttributes(action),
+        },
       },
       ctxBase.trace,
       async (trace) => {
@@ -803,6 +817,8 @@ export class Runtime {
           actionId,
           action: action.name,
           actionKind: action.kind,
+          // Enfileirar devolve o handle do job, não os dados: a exposição é marcada na execução.
+          nature: { kind: action.kind, ...(action.effect !== undefined ? { effect: action.effect } : {}) },
           outcome: 'success',
           durationMs,
           ctx,
@@ -852,6 +868,7 @@ export class Runtime {
           actionId,
           action: action.name,
           actionKind: action.kind,
+          nature: action,
           outcome: 'success',
           durationMs,
           ctx,
@@ -884,6 +901,7 @@ export class Runtime {
           actionId,
           action: action.name,
           actionKind: action.kind,
+          nature: action,
           outcome: 'error',
           durationMs,
           ctx,
@@ -932,6 +950,7 @@ export class Runtime {
       const cfg = normalizeAiConfig(action.ai)
       if (cfg === null) continue
       const dataProducts = [...(this.actionDataProducts.get(action.name) ?? [])].sort()
+      const effect = resolveActionEffect(action)
       tools.push({
         name: action.name,
         ...(action.label !== undefined
@@ -939,7 +958,23 @@ export class Runtime {
           : {}),
         description: cfg.description ?? action.description ?? action.name,
         inputSchema: action.input,
+        // No MCP, `destructiveHint` ausente numa escrita vale `true`. Numa escrita declarada, o valor
+        // vai explícito, para o cliente não tratar como destrutiva o que o Opus não trata.
+        ...(effect !== undefined || cfg.destructive === true
+          ? {
+              annotations: {
+                ...(effect !== undefined ? { readOnlyHint: effect === 'read' } : {}),
+                ...(effect === 'write'
+                  ? { destructiveHint: cfg.destructive === true }
+                  : cfg.destructive === true && effect === undefined
+                    ? { destructiveHint: true }
+                    : {}),
+              },
+            }
+          : {}),
         metadata: {
+          ...(effect !== undefined ? { effect } : {}),
+          ...(action.personalData !== undefined ? { personalData: action.personalData } : {}),
           dataProducts,
           dataProductLabels: Object.fromEntries(
             dataProducts.map((id) => [id, this.dataProducts.get(id)?.label ?? id]),
@@ -1228,6 +1263,8 @@ export class Runtime {
     actionId: string
     action: string
     actionKind?: ActionDef['kind']
+    /** A natureza declarada (ADR 0041): efeito e dado pessoal viajam para o registro. */
+    nature?: Pick<ActionDef, 'kind' | 'effect' | 'personalData'>
     outcome: 'success' | 'error'
     durationMs: number
     ctx: ActionContext
@@ -1253,6 +1290,15 @@ export class Runtime {
     }
     if (args.output !== undefined) record.output = args.output
     if (args.error !== undefined) record.error = args.error
+    if (args.nature !== undefined) {
+      const effect = resolveActionEffect(args.nature)
+      if (effect !== undefined) record.effect = effect
+      // A exposição só existe quando a action devolveu algo: erro não expõe o dado declarado, e a
+      // resposta simulada do modo design (mock, cenário ou gerada) não é de ninguém.
+      if (args.nature.personalData === true && args.outcome === 'success' && args.mode !== 'design') {
+        record.personalData = { records: countReturnedRecords(args.nature.kind, args.output) }
+      }
+    }
     if (args.mode !== undefined) record.meta = { mode: args.mode }
     return record
   }
@@ -1750,6 +1796,15 @@ export class Runtime {
 // Helpers
 // =============================================================================
 
+/** Atributos do span com a natureza declarada da action (ADR 0041). */
+function natureAttributes(action: ActionDef): Record<string, string | boolean> {
+  const effect = resolveActionEffect(action)
+  return {
+    ...(effect !== undefined ? { 'opus.action.effect': effect } : {}),
+    ...(action.personalData !== undefined ? { 'opus.action.personal_data': action.personalData } : {}),
+  }
+}
+
 async function settledSuccessfully<T>(promise: Promise<T>): Promise<boolean> {
   try {
     await promise

package/src/core/types.ts

@@ -356,6 +356,15 @@ export interface AuditRecord {
   output?: unknown
   error?: ActionError
 
+  /** Efeito resolvido da action (ADR 0041): `list` e `view` são sempre leitura. */
+  effect?: ActionEffect
+  /**
+   * Presente quando a action declara `personalData: true` e executou com sucesso (ADR 0041):
+   * a requisição expôs dado pessoal a quem a executou. `records` conta os registros devolvidos
+   * (itens da página de uma `list`, 1 para um objeto) e é `null` quando a saída não permite contar.
+   */
+  personalData?: { records: number | null }
+
   severity: 'info' | 'warning' | 'error'
   /** Campo legado preservado para compatibilidade com sinks/consumers existentes. */
   trace?: {
@@ -709,6 +718,12 @@ export interface ExpandSpec {
 
 export type ActionKind = 'simple' | 'form' | 'list' | 'view'
 
+/**
+ * O que a action faz com o estado (ADR 0041). `list` e `view` são leitura pelo protocolo (`GET`);
+ * `simple` e `form` declaram, porque cobrem as duas coisas.
+ */
+export type ActionEffect = 'read' | 'write'
+
 export type AuthorizeFn<In, Loaded = Record<string, unknown>> = (
   ctx: ActionContext,
   input: In,
@@ -810,6 +825,20 @@ export interface ActionBase<In, Out, ParsedIn = In> {
   input: Schema<In, ParsedIn>
   output: Schema<Out>
 
+  // — Natureza (ADR 0041) —
+  /**
+   * `read` não altera estado; `write` altera. `list` e `view` já são leitura pelo protocolo e não
+   * declaram (declarar `write` nelas é recusado no registro). `simple` e `form` declaram: o `kind`
+   * sozinho não diz se a action lê ou escreve. Declarativo — o runtime não impede o handler.
+   */
+  effect?: ActionEffect
+  /**
+   * A resposta contém dados que identificam pessoas: nome, documento, contato, placa ou texto
+   * livre sobre alguém. Com `true`, toda execução bem-sucedida é marcada no `AuditRecord` e no
+   * span, qualquer que seja o consumidor. Nunca inferido; ausente significa "não declarado".
+   */
+  personalData?: boolean
+
   // — Autorização (fail-closed default) —
   public?: boolean
   requires?: string | string[]
@@ -821,27 +850,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 +932,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,
@@ -1315,12 +1330,23 @@ export interface AiTool {
   title?: string
   description: string
   inputSchema: unknown
+  /** Anotações padrão de ferramenta do MCP, derivadas do contrato (ADR 0041). */
+  annotations?: {
+    /** A ferramenta não altera estado (efeito `read`). */
+    readOnlyHint?: boolean
+    /** A ferramenta pode destruir dados (`ai.destructive`); só faz sentido quando não é leitura. */
+    destructiveHint?: boolean
+  }
   /** Metadados de governança para o host; não fazem parte do prompt nem concedem acesso. */
   metadata?: {
     /** Identificadores técnicos dos Produtos de Dados relacionados. */
     dataProducts?: string[]
     /** Labels humanas por identificador; ausente para runtimes legados. */
     dataProductLabels?: Record<string, string>
+    /** Efeito resolvido; ausente quando `simple`/`form` não declaram. */
+    effect?: ActionEffect
+    /** A action declara devolver dado pessoal; ausente quando não declarou. */
+    personalData?: boolean
   }
 }
 

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/mcp/index.ts

@@ -48,9 +48,15 @@ export function createOpusMcpServer(runtime: Runtime, opts: OpusMcpOptions = {})
       ...(t.title !== undefined ? { title: t.title } : {}),
       description: t.description,
       inputSchema: toJsonSchema(t.inputSchema) as { type: 'object' },
+      // Anotações padrão do MCP (ADR 0041): o cliente sabe se a ferramenta só lê.
+      ...(t.annotations !== undefined ? { annotations: t.annotations } : {}),
       _meta: {
         'com.softize.opus/data-products': t.metadata?.dataProducts ?? [],
         'com.softize.opus/data-product-labels': t.metadata?.dataProductLabels ?? {},
+        ...(t.metadata?.effect !== undefined ? { 'com.softize.opus/effect': t.metadata.effect } : {}),
+        ...(t.metadata?.personalData !== undefined
+          ? { 'com.softize.opus/personal-data': t.metadata.personalData }
+          : {}),
       },
     })),
   }))

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