@softize/opus 22.1.0 → 23.0.0

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/code-style.md

@@ -115,7 +115,7 @@ O extrator cobre três superfícies, sem heurística de nome:
    reprovam em vez de serem executadas e o dicionário mantém um snapshot imutável das entradas;
 3. texto estático em filhos e props de uma allowlist de componentes importados diretamente
    de `@softize/opus/ui*` — por exemplo, `Button`, `DialogTitle`, `DialogBody`,
-   `FieldLabel`, `TabsTrigger`, `Page`, `Input` e `DataState`. Alias e namespace de import
+   `FieldLabel`, `TabsListItem`, `Page`, `Input` e `DataState`. Alias e namespace de import
    continuam rastreáveis. `uppercase`, variantes como `sm:hover:uppercase`, modificadores
    `!uppercase`/`uppercase!` e classes em descendentes são projetados na superfície que
    realmente herda o CSS. Props específicas também respeitam a implementação: por exemplo,

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": "23.0.0",
   "description": "End-to-end action protocol for TypeScript. Single package with subpath exports (core + adapters).",
   "license": "MIT",
   "type": "module",

package/registry/skills/build-opus-ui/references/ui-patterns.md

@@ -52,7 +52,7 @@ ContentDescription, ContentMeta, ContentActions) + ContentBody`. `ContentHeader`
   `toolbarActions` fica reservado a operações que dependem do recorte atual.
 - Card, Drawer e Pane nomeiam a região principal como `CardBody`, `DrawerBody` e `PaneBody`.
   `*Content` permanece reservado a raízes técnicas ou painéis cujo papel não é o corpo de uma
-  estrutura, como `DialogContent`, `PopoverContent` e `TabsContent`.
+  estrutura, como `DialogContent`, `PopoverContent` e `TabsPanel`.
 - Componentes compartilhados não impõem margem externa; páginas e shells compõem layout.
 - A UI assume layout desktop fixo e largura mínima suportada de `64rem`. Não introduzir
   breakpoints de viewport ou container queries isoladas; uma futura responsividade precisa começar

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,14 +1,19 @@
 # Contrato e binding
 
 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.
+declarativa compartilhável. Ele não declara dados de design: no modo design, a action 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).
 
 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 → 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/contracts.ts

@@ -42,7 +42,7 @@ type BindingKeys = 'handler' | 'loads' | 'background' | 'emits' | 'idempotency'
  * `ParsedIn` (o lado PARSEADO do schema de input — defaults aplicados) defaulta
  * a `any` nos contratos, de propósito: quem anota contrato à mão é o CLIENTE
  * (`FormContract<MeuInput, MeuOutput>` em hooks/props), que só conhece o fio —
- * e `authorize`/`mockHandler` são contravariantes em `ParsedIn`, então um
+ * e `authorize` é contravariante em `ParsedIn`, então um
  * default estreito rejeitaria contrato real cujo schema tem `.default()`.
  * Quem precisa do parseado com precisão (`bindAction`) o infere do schema.
  */

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,
@@ -817,16 +833,7 @@ export class Runtime {
       }
 
       // — 5. Handler ————————————————————————————————————————————————————————
-      // Modo design (`OPUS_MODE=design`): tenta mockHandler primeiro, cai
-      // no handler real se não houver. Em qualquer outro modo, handler real
-      // sempre manda. Leitura de env mora aqui, no boundary do execute — o
-      // resto do core continua sem tocar `process.env`.
-      const isDesignMode = isOpusDesignMode()
-      const handlerToRun =
-        isDesignMode && action.mockHandler !== undefined
-          ? action.mockHandler
-          : action.handler
-      const output = await handlerToRun(
+      const output = await action.handler(
         ctx,
         validatedInput,
         loaded,
@@ -834,8 +841,6 @@ export class Runtime {
           ? progress
           : undefined,
       )
-      const usedMock = handlerToRun === action.mockHandler
-
       // — 6. Validate output (dev only) —————————————————————————————————————
       // Search retorna Paginated<Item> mas `output` schema descreve só Item;
       // skipamos pra evitar falso negativo. v1 pode validar items[].
@@ -852,12 +857,12 @@ export class Runtime {
           actionId,
           action: action.name,
           actionKind: action.kind,
+          nature: action,
           outcome: 'success',
           durationMs,
           ctx,
           input: validatedInput,
           output: validatedOutput,
-          mode: usedMock ? 'design' : undefined,
         }),
         action.audit,
       )
@@ -884,6 +889,7 @@ export class Runtime {
           actionId,
           action: action.name,
           actionKind: action.kind,
+          nature: action,
           outcome: 'error',
           durationMs,
           ctx,
@@ -932,6 +938,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 +946,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,14 +1251,14 @@ 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
     input: unknown
     output?: unknown
     error?: ReturnType<typeof error>
-    /** Quando `'design'`, sinaliza que o mockHandler foi executado. */
-    mode?: 'design' | undefined
   }): AuditRecord {
     const record: AuditRecord = {
       id: args.actionId,
@@ -1253,7 +1276,15 @@ export class Runtime {
     }
     if (args.output !== undefined) record.output = args.output
     if (args.error !== undefined) record.error = args.error
-    if (args.mode !== undefined) record.meta = { mode: args.mode }
+    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. O plugin de design remove o marcador
+      // das respostas simuladas antes de registrar a action no runtime.
+      if (args.nature.personalData === true && args.outcome === 'success') {
+        record.personalData = { records: countReturnedRecords(args.nature.kind, args.output) }
+      }
+    }
     return record
   }
 
@@ -1750,6 +1781,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
@@ -2040,21 +2080,3 @@ function generateId(): string {
   // fallback determinístico-suficiente quando crypto não disponível
   return `id_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`
 }
-
-/**
- * Único ponto do core que lê `process.env`. Usado pelo `execute()` pra
- * decidir entre `handler` real e `mockHandler`. Isolado em função pra
- * testabilidade — testes podem `vi.stubEnv('OPUS_MODE', ...)`.
- *
- * Mantém a invariante "core nunca lê env" intacta no resto do código:
- * adapters/config seguem recebendo valores literais.
- *
- * Exportado (fora do index público) pro harness de `testing` aplicar a MESMA
- * régua no `runAction` — a semântica de design mora num lugar só.
- */
-export function isOpusDesignMode(): boolean {
-  // Acesso via globalThis: defensivo pra runtimes sem `process` (browser, edge) E
-  // não exige @types/node no consumidor que compila este source (apps web).
-  const g = globalThis as { process?: { env?: Record<string, string | undefined> } }
-  return g.process?.env?.['OPUS_MODE'] === 'design'
-}