@softize/opus 22.1.0 → 22.2.0

package/CHANGELOG.md

@@ -7,6 +7,41 @@ 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

package/bin/cli.mjs

@@ -40,7 +40,8 @@ async function cmdCheck(dir) {
     for (const error of materialization.errors) log('error', `✗ opus check: ${error}`)
     process.exit(1)
   }
-  const { files, actions, contracts, deprecatedMockHandlers, 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(
@@ -50,6 +51,14 @@ async function cmdCheck(dir) {
     )
   }
 
+  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 })
     // Projeto MARCADO (opus.json) sem actions passa vacuamente — server/lib/app sem

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;
     }
@@ -644,6 +653,9 @@ export function checkProject(sources) {
   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);
@@ -669,6 +681,11 @@ export function checkProject(sources) {
       }
       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;
+      }
     }
   }
 
@@ -775,6 +792,8 @@ export function checkProject(sources) {
     contracts,
     dataProducts: productDeclarations.length,
     deprecatedMockHandlers,
+    missingEffect,
+    missingPersonalData,
     findings,
   };
 }
@@ -1956,6 +1975,8 @@ export async function scanDir(rootDir) {
     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/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.1.0",
+  "version": "22.2.0",
   "description": "End-to-end action protocol for TypeScript. Single package with subpath exports (core + adapters).",
   "license": "MIT",
   "type": "module",

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

@@ -9,6 +9,11 @@ O binding contém `handler`, `loads`, autorização dependente de dados carregad
 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 → 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,6 +17,7 @@ ${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',
 })`
   }
@@ -28,6 +29,8 @@ ${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' } },
 })`
   }
@@ -38,6 +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() }),
+  // personalData: decida — true se a resposta identifica pessoas (nome, documento, contato).
 })`
   }
   return `export const ${identifier} = defineContract({
@@ -47,6 +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() }),
+  effect: 'write',
+  // personalData: decida — true se a resposta identifica pessoas (nome, documento, contato).
 })`
 }
 

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

@@ -17,6 +17,8 @@ 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',
 })
 

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/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[]
@@ -1301,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/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/ui/docs/content/actions.md

@@ -132,7 +132,7 @@ nessa estrutura. Os grupos seguem esta sequência; dentro de cada grupo, a ordem
 ```text
 name, kind
   → label, title, summary, description, icon, color, messages, tags, examples, errors
-  → input, output
+  → input, output, effect, personalData
   → public, requires, authorize, loads
   → handler, mockHandler
   → audit, confirm, invalidates, rateLimit, idempotency
@@ -146,6 +146,35 @@ Declare `input` e `output` com `z.object` e use os tipos lógicos do catálogo e
 validações: `z.object({ tag: t.slug().zod(), contato: t.email().zod() })`. O `.zod()` devolve o
 schema zod de cada tipo lógico (slug, email, phone, money…), importado de `@softize/opus/schema/zod`.
 
+## Declarar o que a action faz com os dados
+
+Dois fatos sobre a action valem para qualquer consumidor, da interface à IA, e ficam declarados no
+contrato:
+
+- **`effect`** diz se a action só lê (`'read'`) ou altera estado (`'write'`). `list` e `view` já são
+  leitura, porque são servidas por `GET`, e não precisam declarar. `simple` e `form` declaram,
+  porque o `kind` não diz isso: uma análise sob demanda costuma ser `simple` e só ler.
+- **`personalData`** diz se a resposta contém dados que identificam pessoas, como nome, documento,
+  contato, placa ou texto livre sobre alguém. `false` também é uma declaração.
+
+```ts
+export const salesPerformanceContract = defineContract({
+  name: 'sales.performance',
+  kind: 'simple',
+  input: z.object({ period: z.string() }),
+  output: z.object({ total: z.number() }),
+  effect: 'read',
+  personalData: false,
+})
+```
+
+Com `personalData: true`, toda execução bem-sucedida fica marcada no registro de auditoria com a
+quantidade de registros devolvidos, inclusive quando a action declara `audit: false`; nesse caso o
+registro é mínimo, sem entrada nem saída. No modo design, a resposta simulada não é marcada. Um
+host de IA pode usar `effect` para decidir o que oferecer ao modelo sem procedimento, e o MCP publica
+a anotação `readOnlyHint`. O `opus check` avisa quantas actions ainda não declaram os dois fatos; uma
+major futura passará a exigi-los.
+
 A autorização é fechada por padrão: sem `public: true`, a action exige usuário autenticado; com
 `authorize`, exige também a permissão declarada. `automatable: true` permite que um
 [schedule](/docs/scheduler) execute a action como o sistema, sem abri-la a chamadores anônimos.

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

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