@softize/opus 22.0.0 → 22.2.0

package/CHANGELOG.md

@@ -7,6 +7,65 @@ 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.2.0 — 2026-09-29
+
+As actions passam a declarar o que fazem com os dados (ADR 0041). Dois campos novos no contrato,
+ambos opcionais nesta versão:
+
+- **`effect: 'read' | 'write'`** diz se a action só lê ou altera estado. `list` e `view` já são
+  leitura, porque são servidas por `GET`, e não declaram; declarar `effect: 'write'` nelas é recusado
+  ao registrar a action (`runtime.invalid_action_effect`) e apontado pelo `opus check`. `simple` e
+  `form` declaram.
+- **`personalData: boolean`** diz se a resposta contém dados que identificam pessoas.
+
+Com os dois declarados, o runtime:
+
+- marca no `AuditRecord` toda execução bem-sucedida de action com `personalData: true`
+  (`personalData: { records }`, com a quantidade devolvida) e registra `effect`, qualquer que seja o
+  consumidor. Com `audit: false`, a exposição ainda gera um registro mínimo, sem entrada nem saída
+  (`meta.exposureOnly`). Execução com erro, enfileiramento em segundo plano e resposta simulada do
+  modo design não são marcados;
+- acrescenta `opus.action.effect` e `opus.action.personal_data` aos atributos do span;
+- projeta `effect` e `personalData` no manifest;
+- publica nas ferramentas de IA (`runtime.aiTools()`) e no `ListTools` do MCP as anotações
+  `readOnlyHint` e `destructiveHint` (numa escrita, sempre explícito, porque o MCP trata a ausência
+  como destrutiva), e em `_meta` os campos `com.softize.opus/effect` e
+  `com.softize.opus/personal-data`.
+
+O `opus check` conta, numa linha de aviso que não reprova, quantas actions `simple` ou `form` não
+declaram `effect` e quantas actions não declaram `personalData`.
+
+**O que fazer:** rode `opus gen` depois do bump. O manifest passa a ter `effect` e `personalData` em
+toda action (`null` quando não declarado), e sem regenerar o `manifest:check` falha mesmo sem mudança
+de código. O resto é gradual: declare `effect` nas actions `simple` e `form` e `personalData` em
+todas; uma major futura passará a exigir as duas declarações. Um sink de audit que descarta leituras
+(`actionKind` `list` ou `view`) deve preservar as que trazem `personalData`, se a aplicação precisar
+registrar a exposição.
+
+## 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,24 @@ 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, missingEffect, missingPersonalData, 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 (missingEffect > 0 || missingPersonalData > 0) {
+    log(
+      'warn',
+      `⚠ opus check: ${missingEffect} action(s) simple/form sem \`effect\` e ${missingPersonalData} sem \`personalData\`. ` +
+        'Declare se a action lê ou escreve e se devolve dado pessoal; uma major futura passará a exigir as duas declarações (ADR 0041).',
+    )
+  }
 
   if (actions === 0 && findings.length === 0) {
     const verdict = emptyScanVerdict({ hasMarker, contracts })

package/bin/lib/check.mjs

@@ -51,6 +51,8 @@ const FIELD_GROUP = {
   errors: 1,
   input: 2,
   output: 2,
+  effect: 2,
+  personalData: 2,
   public: 3,
   requires: 3,
   authorize: 3,
@@ -515,6 +517,7 @@ export function parseActions(fileName, sourceText) {
           form: callee,
           name: strProp(obj, "name"),
           kind: strProp(obj, "kind"),
+          effect: strProp(obj, "effect"),
           keys: objKeys(obj),
           ident: constIdent(node),
           exported: isExported(node),
@@ -575,6 +578,12 @@ export function lintAction(a) {
   if (!a.kind) at("kind", `${a.form} sem \`kind\``);
   else if (!KINDS.has(a.kind))
     at("kind", `kind "${a.kind}" inválido (use simple|form|list|view)`);
+  // ADR 0041: list e view são servidas por GET — leitura pelo protocolo.
+  if ((a.kind === "list" || a.kind === "view") && a.effect === "write")
+    at(
+      "effect",
+      `${a.kind} é servida por GET e não pode declarar effect: 'write'; use simple ou form para escrever`,
+    );
 
   // field-order: os campos conhecidos devem ter group-index não-decrescente
   let lastGroup = -1;
@@ -585,7 +594,7 @@ export function lintAction(a) {
     if (g < lastGroup) {
       at(
         "field-order",
-        `campo "${k}" fora de ordem (depois de "${lastKey}") — siga identidade→docs→input/output→authorize→handler→comportamento`,
+        `campo "${k}" fora de ordem (depois de "${lastKey}") — siga identidade→docs→input/output e natureza (effect, personalData)→authorize→handler→comportamento`,
       );
       break;
     }
@@ -642,6 +651,11 @@ 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;
+  // Natureza da action (ADR 0041): declarações ausentes são contadas, não reprovadas, na minor.
+  let missingEffect = 0;
+  let missingPersonalData = 0;
 
   for (const { file, text } of sources) {
     const declarations = parseDataProducts(file, text);
@@ -666,6 +680,12 @@ 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;
+      if (item.form !== "bindAction") {
+        const writesByGet = item.kind === "list" || item.kind === "view";
+        if (!writesByGet && !item.keys.includes("effect")) missingEffect += 1;
+        if (!item.keys.includes("personalData")) missingPersonalData += 1;
+      }
     }
   }
 
@@ -771,6 +791,9 @@ export function checkProject(sources) {
     actions,
     contracts,
     dataProducts: productDeclarations.length,
+    deprecatedMockHandlers,
+    missingEffect,
+    missingPersonalData,
     findings,
   };
 }
@@ -1921,7 +1944,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 +1974,9 @@ export async function scanDir(rootDir) {
     actions: checked.actions,
     contracts: checked.contracts,
     dataProducts: checked.dataProducts,
+    deprecatedMockHandlers: checked.deprecatedMockHandlers,
+    missingEffect: checked.missingEffect,
+    missingPersonalData: checked.missingPersonalData,
     findings: [...checked.findings, ...uiFindings],
     hasMarker,
   };

package/bin/lib/gen-manifest.mjs

@@ -53,6 +53,8 @@ function shapeAction(a) {
     authorize: a.authorize,
     public: a.public,
     automatable: a.automatable,
+    effect: a.effect ?? null,
+    personalData: a.personalData ?? null,
     internal: a.internal,
     successStatus: a.successStatus,
     input: a.input,

package/bin/lib/gen-runner.mjs

@@ -51,6 +51,8 @@
  *       successStatus?: number,
  *       public?: boolean,
  *       automatable?: boolean,             // aceita execução pelo sistema (ADR 0028)
+ *       effect: 'read'|'write'|null,       // efeito resolvido; list/view = read (ADR 0041)
+ *       personalData: boolean|null,        // devolve dado pessoal; null = não declarado
  *       internal?: boolean,
  *       rateLimit?: { window, max },
  *       confirm?: ConfirmSpec,
@@ -375,6 +377,9 @@ function serializeAction(action, ctx) {
     authorize: serializeAuthorize(action.authorize),
     public: action.public === true,
     automatable: action.automatable === true,
+    // ADR 0041: `list` e `view` são leitura pelo protocolo; null = não declarado.
+    effect: action.kind === "list" || action.kind === "view" ? "read" : (action.effect ?? null),
+    personalData: typeof action.personalData === "boolean" ? action.personalData : null,
     internal: action.internal === true,
     successStatus: action.successStatus,
     input: safeToJsonSchema(action.input, ctx),

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/docs/adr/0041-actions-declare-effect-and-personal-data.md

@@ -0,0 +1,139 @@
+# ADR 0041 — Actions declaram efeito e dado pessoal
+
+- **Status:** aceita; saiu na 22.2.0.
+- **Data:** 2026-09-29.
+- **Relacionadas:** ADR 0028 (execução pelo sistema); ADR 0104 da Grand Brasil (actions são a
+  interface da IA).
+
+## Contexto
+
+Uma action é consumida pela interface, pela IA, por automações e por outros sistemas via MCP. Dois
+fatos sobre ela importam a todos esses consumidores e hoje não estão declarados em lugar nenhum.
+
+**Efeito.** Quem oferece uma action a um modelo precisa saber se ela só lê ou se altera estado. O
+`kind` responde isso só em parte:
+
+- `list` e `view` são servidas por `GET`, que o protocolo HTTP define como seguro, sem efeito
+  colateral;
+- `simple` e `form` são servidas por `POST` e cobrem as duas coisas. Na Grand Brasil, em setembro de
+  2026, `sales.performance`, `doc.search`, `facts.query` e `sale.view` eram leituras declaradas como
+  `simple`.
+
+O MCP tem uma anotação padrão para isso, `readOnlyHint`, que o Opus não preenche.
+
+**Dado pessoal.** Uma action que devolve nome, documento, contato ou texto livre sobre pessoas expõe
+dado pessoal a quem a executa. A aplicação precisa registrar essa exposição em toda requisição,
+qualquer que seja o consumidor, para auditoria e LGPD. Hoje o registro da requisição (`AuditRecord`)
+não distingue uma execução que expôs dado pessoal de outra que não expôs, e cada consumidor teria
+de lembrar de marcar por conta própria.
+
+Os dois fatos pertencem à action, não à IA: valem para qualquer consumidor. Por isso não cabem na
+configuração `ai`.
+
+## Decisão
+
+### 1. Dois campos no contrato
+
+```ts
+defineContract({
+  name: 'sales.performance',
+  kind: 'simple',
+  description: 'Soma as vendas por período e dimensão.',
+  input: salesPerformanceInput,
+  output: salesPerformanceOutput,
+  effect: 'read',
+  personalData: false,
+})
+```
+
+Os dois campos ficam no grupo de `input` e `output` da ordem canônica, cobrada pelo `opus check`.
+
+- **`effect: 'read' | 'write'`.** `list` e `view` são leitura pelo protocolo e não precisam
+  declarar; declarar `effect: 'write'` nelas é erro de configuração, recusado ao registrar a action.
+  `simple` e `form` declaram.
+- **`personalData: boolean`.** Declara se a resposta contém dados que identificam pessoas. Não é
+  inferido de nada. `false` é uma declaração tão explícita quanto `true`; ausente significa "não
+  declarado".
+
+### 2. O runtime marca a exposição em toda requisição
+
+Quando uma action com `personalData: true` executa com sucesso, o `AuditRecord` passa a carregar:
+
+```ts
+personalData: { records: number | null }
+```
+
+`records` conta os registros devolvidos: os itens da página de uma `list`, os elementos de um array,
+1 para um objeto e `null` quando a forma da saída não permite contar. Numa `view`, `simple` ou `form`,
+um campo `items` faz parte do registro, e o objeto continua contando como um.
+
+A marca vale mesmo quando a action declara `audit: false`: nesse caso, o runtime emite um registro
+mínimo, sem entrada nem saída e com `meta.exposureOnly`, para todos os sinks. Desligar a auditoria
+serve para reduzir ruído, não para esconder exposição. Com `auditMode: 'strict'`, a falha de um sink
+nesse registro mínimo derruba a requisição, como em qualquer outro registro. Com `AuditConfig.sink`, o registro vai só ao
+sink indicado, com a marca. Não são marcados: a execução com erro, o enfileiramento em segundo plano
+(que devolve o handle do job; a marca sai na execução do job) e a resposta simulada do modo design
+(mock, cenário ou resposta gerada); um handler real executado no modo design continua marcado. O registro também carrega `effect`. O span da execução
+recebe os atributos `opus.action.effect` e `opus.action.personal_data`, que são declarações
+conhecidas antes da execução; a contagem fica no registro, porque o span é aberto antes de haver
+saída.
+
+A marca é do runtime, não do consumidor: tela, IA, automação e MCP passam pelo mesmo `execute`.
+
+### 3. Projeções
+
+- **Manifest:** cada action projeta `effect`, já resolvido para `list` e `view`, e `personalData`.
+- **`runtime.aiTools()`:** cada ferramenta carrega `annotations.readOnlyHint` e
+  `annotations.destructiveHint`, e `metadata.personalData`. No MCP, `destructiveHint` ausente numa
+  escrita vale `true`; por isso, numa action com `effect: 'write'`, ele vai sempre explícito, a partir
+  de `ai.destructive`.
+- **MCP:** o `ListTools` publica as mesmas `annotations` e acrescenta
+  `com.softize.opus/effect` e `com.softize.opus/personal-data` em `_meta`.
+
+### 4. Adoção gradual
+
+Nesta minor, os dois campos são opcionais. O `opus check` conta, numa linha de aviso que não
+reprova, quantas actions `simple` ou `form` não declaram `effect` e quantas actions não declaram
+`personalData`. A obrigatoriedade fica para uma major, depois que o consumidor declarar tudo.
+
+## Consequências
+
+- O host de IA decide pela declaração, e não por `kind`, nome ou descrição, o que entra no turno
+  sem procedimento.
+- A auditoria de exposição de dado pessoal passa a ser propriedade do runtime.
+- Consumidores precisam classificar retroativamente as actions que já existem. O aviso do
+  `opus check` mede o que falta.
+- `effect` é declarativo: o runtime não impede uma action `read` de escrever. A garantia vem do
+  handler e da revisão.
+
+## Alternativas descartadas
+
+### Declarar na configuração `ai`
+
+Seria menor, mas os dois fatos valem para todo consumidor. A marca de dado pessoal precisa existir
+também em requisições da interface e de automações.
+
+### Inferir leitura de `kind` para todos os kinds
+
+Funciona para `list` e `view`, por causa do `GET`. Para `simple` e `form`, a inferência erraria as
+leituras declaradas como `simple` e daria à convenção um papel de segurança.
+
+### Classificação rica de sensibilidade
+
+Um enum com dado financeiro, de saúde ou sigiloso seria mais expressivo, mas nenhum consumidor tem
+política para essas categorias hoje. O campo booleano cobre a necessidade atual e pode evoluir para
+uma classificação sem mudar o ponto de declaração.
+
+## Verificação
+
+- Registrar `effect: 'write'` em `list` ou `view` falha na subida do runtime.
+- O manifest projeta `effect: 'read'` para `list` e `view` sem declaração.
+- `aiTools()` e o `ListTools` do MCP publicam `readOnlyHint` a partir do efeito resolvido.
+- Execução bem-sucedida de action com `personalData: true` produz `AuditRecord.personalData` com a
+  contagem, e o span recebe os atributos de efeito e de dado pessoal.
+- Execução com erro, enfileiramento em segundo plano, modo design e action com `personalData: false`
+  não produzem a marca; a execução do job produz.
+- Com `audit: false`, a exposição gera registro mínimo, sem entrada nem saída.
+- `records` conta a página numa `list` e 1 numa `view` com campo `items`.
+- Escrita sem `ai.destructive` publica `destructiveHint: false`.
+- O `opus check` conta as declarações ausentes sem reprovar.

package/docs/protocol.md

@@ -79,6 +79,10 @@ type ActionBase<In, Out> = {
   input:  Schema<In>                    // StandardSchemaV1-compatible
   output: Schema<Out>
 
+  // — Natureza (ADR 0041) —
+  effect?:       'read' | 'write'       // list/view = read pelo GET; simple/form declaram
+  personalData?: boolean                // devolve dado que identifica pessoas; marca o audit
+
   // — Autorização (fail-closed default) —
   public?:    boolean                   // default false
   requires?:  string | string[]         // permissão declarativa (drive OpenAPI/docs)
@@ -628,6 +632,8 @@ Toda action **audita por default**. Para desabilitar (raramente justificável),
 
 > Audit é o **log de negócio** de mudanças de estado. Não confundir com logging de aplicação (debug, info) — esses ficam por conta do logger do projeto.
 
+**Exposição de dado pessoal (ADR 0041).** Quando a action declara `personalData: true` e executa com sucesso, o registro carrega `personalData: { records }`, com a quantidade de registros devolvidos (os itens da página de uma `list`, 1 para um objeto, `null` quando a saída não permite contar). A marca é do runtime: vale para a interface, a IA, automações e o MCP, sem que o consumidor precise lembrar. O registro também carrega `effect`. Não recebem a marca: a execução com erro; o enfileiramento de uma action em segundo plano, que devolve o handle do job (a marca sai na execução do job); e a resposta simulada do modo design (mock, cenário ou resposta gerada); um handler real executado no modo design continua marcado. Com `audit: false`, a execução que expôs dado pessoal ainda gera um registro mínimo, sem entrada nem saída e com `meta.exposureOnly`, entregue a todos os sinks. Com `auditMode: 'strict'`, a falha de um sink nesse registro derruba a requisição, como em qualquer outro registro. Com `AuditConfig.sink`, o registro, com a marca, vai só ao sink indicado. `records` conta os itens da página numa `list`; em `view`, `simple` e `form`, um objeto conta como um registro, mesmo que tenha um campo `items`.
+
 ### Shape do registro
 
 ```ts
@@ -649,6 +655,11 @@ type AuditRecord = {
   output?: unknown;           // já redacted, presente apenas em success
   error?:  ActionError;       // presente apenas em outcome=error
 
+  effect?: 'read' | 'write';   // efeito resolvido (ADR 0041); list/view = read
+  personalData?: {             // exposição de dado pessoal (ADR 0041)
+    records: number | null;    // registros devolvidos; null = não contável
+  };
+
   severity: 'info' | 'warning' | 'error';
   trace?: {                    // campo legado — compatibilidade
     requestId?: string;
@@ -667,8 +678,8 @@ defineAction({
 })
 
 defineAction({
-  audit: false,                 // desabilita (precisa justificar em PR)
-})
+  audit: false,                 // desabilita (precisa justificar em PR); exposição de
+})                              // dado pessoal ainda gera registro mínimo (ADR 0041)
 
 defineAction({
   audit: {
@@ -2171,6 +2182,8 @@ chamada, inclusive por IA e MCP.
 - **`automatable`** — opt-in que permite a um schedule executar a action como o sistema, sem usuário. Negado por padrão; não abre a action a anônimos. Distinta de `ai.enabled`. Ver §4.
 - **`isSystemActor(ctx)`** — responde se a execução foi criada pelo runtime para o sistema (schedule ou job que ele enfileirou). Usado no `authorize` de actions `automatable`. Ver §4.
 - **`internal`** — flag que indica action service-to-service apenas; server adapter não expõe como REST público. Ver §2.
+- **`effect`** — o que a action faz com o estado: `read` ou `write`. `list` e `view` são leitura pelo `GET` e não declaram; `simple` e `form` declaram. Projetado no manifest, nas ferramentas de IA e no MCP (`readOnlyHint`). Ver ADR 0041.
+- **`personalData`** — a resposta contém dados que identificam pessoas. Com `true`, toda execução bem-sucedida é marcada no `AuditRecord` (`personalData.records`) e no span, qualquer que seja o consumidor. Ver §5 e ADR 0041.
 - **Reaction** — declaração que escuta evento(s) e executa handler. Auto-registrada pelo runtime via EventBusAdapter. Pareada com Action (ator inicia × sistema reage). Ver §12.
 - **`defineReaction`** — função que constrói uma reaction declarativa.
 - **`ReactionContext`** — contexto entregue ao handler de reaction (user, tenant, db, emit, log, meta).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softize/opus",
-  "version": "22.0.0",
+  "version": "22.2.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/SKILL.md

@@ -15,6 +15,7 @@ registrados no runtime do projeto.
 
 - nome `<resource>.<verb>` e `kind` (`simple`, `form`, `list` ou `view`);
 - comportamento, autorização, input, output, erros e efeitos esperados;
+- se a action só lê ou altera estado e se a resposta contém dados que identificam pessoas;
 - caminhos reais de `shared` e `api` adotados pelo repo.
 
 ## Procedimento
@@ -23,8 +24,12 @@ registrados no runtime do projeto.
 2. Colocar o contrato em módulo importável pelos consumidores e o binding no lado servidor.
 3. Substituir os exemplos do scaffold por schemas, descrições e comportamento do domínio.
 4. Declarar `requires` somente com `authorize` efetivo; `requires` sozinho não protege a action.
-5. Exportar e registrar o binding no domínio/runtime existente.
-6. Carregar e seguir `$test-opus-action` para cobrir contrato, sucesso, erros e efeitos relevantes.
+5. Declarar `effect` em `simple` e `form` e `personalData` em todos os kinds. O scaffold parte de
+   `effect: 'write'` e deixa `personalData` comentado de propósito: a ausência aparece no aviso do
+   `opus check` até alguém decidir, porque um `false` preenchido por padrão esconderia exposição de
+   dado pessoal.
+6. Exportar e registrar o binding no domínio/runtime existente.
+7. Carregar e seguir `$test-opus-action` para cobrir contrato, sucesso, erros e efeitos relevantes.
 
 ## Verificação
 

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

@@ -1,12 +1,19 @@
 # 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
+O contrato também declara o que a action faz com os dados (ADR 0041): `effect` (`read` ou
+`write`) em `simple` e `form`, porque `list` e `view` já são leitura pelo `GET`, e `personalData`
+em todos os kinds. Os dois fatos alimentam a auditoria de exposição de dado pessoal, as ferramentas
+de IA e as anotações do MCP.
+
+Ordem cobrada pelo check: identidade → documentação → input/output e natureza (`effect`,
+`personalData`) → autorização → 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/references/evaluations.md

@@ -3,3 +3,6 @@
 - Dispara: “Crie a action `invoice.approve` no Opus.”
 - Não dispara: “Crie uma função TypeScript que soma duas parcelas.”
 - Execução: gerar contrato e binding para cada kind e obter zero findings no `opus check`.
+- Execução: “Crie `customer.list`, que lista clientes com nome e telefone” resulta em
+  `personalData: true` declarado; “Crie `sales.performance`, que soma vendas por mês” resulta em
+  `effect: 'read'` e `personalData: false`.

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

@@ -17,8 +17,8 @@ ${common}
   description: 'Descreva o comportamento de negócio e seus limites.',
   input: z.object({}),
   output: z.object({ id: z.string() }),
+  // personalData: decida — true se a resposta identifica pessoas (nome, documento, contato).
   paginate: 'cursor',
-  mockHandler: async () => ({ items: [], cursor: { next: null }, total: 0 }),
 })`
   }
   if (kind === 'form') {
@@ -29,8 +29,9 @@ ${common}
   messages: { success: 'Operação concluída.', error: 'Não foi possível concluir.' },
   input: z.object({ id: z.string() }),
   output: z.object({ id: z.string() }),
+  effect: 'write',
+  // personalData: decida — true se a resposta identifica pessoas (nome, documento, contato).
   fields: { id: { label: 'Identificador' } },
-  mockHandler: async (_ctx, input) => ({ id: input.id }),
 })`
   }
   if (kind === 'view') {
@@ -40,7 +41,7 @@ ${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 }),
+  // personalData: decida — true se a resposta identifica pessoas (nome, documento, contato).
 })`
   }
   return `export const ${identifier} = defineContract({
@@ -50,7 +51,8 @@ ${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 }),
+  effect: 'write',
+  // personalData: decida — true se a resposta identifica pessoas (nome, documento, contato).
 })`
 }
 

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.