@softize/opus 25.0.0 → 25.2.0

package/docs/adr/0053-read-action-declares-the-resource-assistant.md

@@ -0,0 +1,443 @@
+# ADR 0053 — A action de leitura declara o assistente do recurso
+
+- **Status:** aceita.
+- **Data:** 2026-10-03.
+- **Complementa:** ADR 0041 (efeito e dado pessoal no contrato) e ADR 0013 (Presentation como
+  artefato portátil orientado a action).
+- **Relacionadas:** ADR 0111 da Grand Brasil, primeiro consumidor desta decisão; ADRs 0004, 0069,
+  0087, 0103 e 0104 da Grand Brasil.
+
+## Contexto
+
+Um produto feito com o Opus pode oferecer, além do chat geral, um chat especializado num recurso: a
+conversa sobre um cliente, um relatório ou um fluxo. Esse chat precisa saber três coisas: como ler
+o recurso e conferir se a pessoa ainda pode vê-lo, qual procedimento a IA segue ao tratar dele e
+quais dados do recurso entram na conversa. Hoje nenhuma dessas três coisas está no contrato.
+
+A Grand Brasil mostra o custo de deixá-las fora. Cada uma mora num lugar diferente, escrita à mão:
+
+- O procedimento e a persona de cada tipo de recurso estão numa tabela no motor de IA
+  (`services/ai/src/resource-assistant.ts:17-61`).
+- O dado que vai ao chat é montado na interface, tela por tela
+  (`apps/main/src/copilot/context.ts:89-139`).
+- A conferência de acesso é uma rota com um `if` por tipo
+  (`services/main/src/server/main.ts:207-262`). Para relatórios, são duas rotas que chamam a regra
+  de acesso do domínio direto, sem passar pela action `report.read`
+  (`services/main/src/server/report-access-route.ts:22-37` e
+  `services/main/src/server/report-routes.ts:28-44`). A leitura do relatório por essas rotas não
+  gera registro de auditoria nem aparece na Lente.
+
+O que o Opus já projeta não basta para mostrar esse desenho:
+
+- O manifest projeta `effect` e `personalData`, mas não a configuração `ai`
+  (`bin/lib/gen-manifest.mjs:39-68`). Quem lê o manifest não sabe nem se a action está publicada
+  para a IA.
+- A Lente (`@softize/lens`) lê o manifest e, por action, mostra nome, tipo, documentação,
+  permissão, eventos, entrada e saída (`lens/src/structure.ts:318-333`). Não mostra efeito, dado
+  pessoal, publicação para a IA nem assistente.
+- `runtime.aiTools()` (`src/core/runtime.ts:997-1037`) e o `ListTools` do MCP
+  (`src/mcp/index.ts:54-60`) carregam efeito, dado pessoal e Produtos de Dados. O motor de IA da
+  Grand Brasil já lê esses metadados pelo MCP (`services/ai/src/mcp.ts:93-101`). É um canal pronto
+  para levar a declaração ao host.
+- A Presentation já declara `assistant: { triggerLabel }` (`src/core/presentation.ts:125-130` e
+  `160`). Essa declaração cobre só a interface: o botão e a divisão da superfície. Não diz o que o
+  chat faz.
+
+As forças em tensão:
+
+- **Um lugar só.** Leitura, conferência de acesso, procedimento e dado ao modelo precisam vir da
+  mesma declaração, para não divergirem.
+- **Contrato compartilhável.** O contrato roda no cliente e no servidor. A declaração não pode
+  carregar função de servidor, banco nem segredo, e precisa caber no manifest.
+- **O procedimento é dado do consumidor.** Na Grand Brasil, Habilidades são registros
+  administráveis no banco do serviço de IA. O Opus não as conhece, e o `opus check`, que é
+  estático, não as alcança.
+- **O dado ao modelo é mínimo, limitado e tratado como dado.** A Grand Brasil já decidiu que texto
+  vindo de fora entra no turno como bloco delimitado, nunca como instrução (ADR 0004 dela, seção
+  3), e pôs teto no que entra no turno (seção 2 da mesma ADR). Uma projeção sem teto repetiria o
+  problema de custo e de diluição do prompt que motivou aquela decisão.
+- **Dado pessoal.** O dado do recurso pode identificar pessoas. A marca de exposição já é do
+  runtime (ADR 0041) e precisa continuar valendo.
+- **Fronteira do SDK.** Persona, regras de negócio e o que cada tipo de recurso significa são do
+  consumidor.
+
+## Decisão
+
+### 1. Uma action `view` pode declarar o assistente do recurso que ela lê
+
+O contrato ganha o campo opcional `assistant`. A action que o declara passa a ser a **action dona**
+daquele tipo de recurso: é por ela que o recurso é lido e que o acesso a ele é conferido.
+
+```ts
+export const customerViewContract = defineContract({
+  name: 'customer.view',
+  kind: 'view',
+  label: 'Ver cliente',
+  description: 'Reúne o cadastro canônico, a qualidade dos contatos e o relacionamento comercial.',
+  input: z.object({ id: z.string().uuid() }),
+  output: customerViewSchema,
+  personalData: true,
+  requires: commercialRead,
+  authorize: anyPerm(...commercialRead),
+  ai: true,
+  assistant: {
+    resource: 'customer',
+    skill: 'review-customer',
+    label: 'Assistente do cliente',
+    title: 'name',
+    context: ['kind', 'stage', 'sources', 'leads.totalCount', 'leads.latest.status'],
+  },
+})
+```
+
+O exemplo deixa fora do contexto contato, documento, data de nascimento e endereço. O nome já vai
+como `title` e não se repete em `context`.
+
+| Campo | O que declara |
+| --- | --- |
+| `resource` | O tipo de recurso de que a action é dona. Identificador em camelCase, único no runtime. |
+| `skill` | A chave do procedimento que a IA segue ao tratar desse recurso, no registro do consumidor. |
+| `label` | O nome do assistente para pessoas. Entra no inventário do `opus copy`. |
+| `title` | O caminho, na saída, do campo que nomeia o recurso para pessoas. |
+| `context` | Os caminhos, na saída, dos campos que o host pode entregar ao modelo como dado do recurso. |
+| `maxContextChars` | Opcional. Teto do dado serializado: padrão de 4.000 caracteres, mínimo de 1.000 e máximo de 16.000. |
+
+Regras da declaração:
+
+- Só uma action `view` declara assistente. A leitura de um recurso identificado é o papel da `view`.
+- A action precisa estar publicada para a IA (`ai` habilitado). Um assistente cujo recurso a IA
+  não pode ler seria uma contradição.
+- A action precisa declarar `personalData`, `true` ou `false`. Com assistente, a declaração deixa
+  de ser opcional, porque decide como o host trata o dado que entrega ao modelo.
+- A entrada é um objeto em que `id`, do tipo texto, é o único campo obrigatório; outros campos, se
+  houver, têm valor padrão. É só com `{ id }` que o runtime pede o recurso.
+- Os caminhos usam ponto para descer em objetos (`leads.totalCount`). Um caminho que passa por uma
+  lista se aplica a cada item. Um caminho pode atravessar um campo anulável, como `leads` em
+  `customer.view`: quando o valor intermediário é `null`, a projeção entrega `null` naquele ponto.
+- Cada `resource` tem uma única action dona no runtime.
+
+`assistant` fica no grupo de integração da ordem canônica, o mesmo de `ai`. O `opus check` confere
+o grupo, não a posição dentro dele (`bin/lib/check.mjs:48-77`).
+
+### 2. O runtime lê o recurso pela action dona
+
+O runtime ganha duas leituras:
+
+- **`runtime.assistants()`** devolve a lista das declarações registradas, com a action dona de
+  cada uma. Serve ao consumidor para montar rotas e telas a partir da declaração, sem lista
+  paralela, e para conferir as chaves de procedimento onde também tiver o registro (seção 5).
+- **`runtime.readResource(resource, id, base)`** executa a action dona com `{ id }` pelo mesmo
+  `execute` de qualquer chamada. A autorização, a auditoria, a marca de dado pessoal e o span são
+  os da action. Em caso de sucesso, devolve:
+
+  ```ts
+  {
+    ok: true,
+    resource: { kind: 'customer', id, title: 'Maria Souza', label: 'Assistente do cliente', skill: 'review-customer' },
+    context: { data: { ... }, truncated: false, omitted: [], personalData: true },
+  }
+  ```
+
+  Em caso de falha, devolve o erro da action, com a categoria dela. Um tipo de recurso sem action
+  dona devolve `runtime.assistant_resource_unknown`, sem executar nada.
+
+Não há outro caminho no SDK para ler o recurso de um assistente. A declaração não exporta regra de
+acesso, consulta nem atalho que dispense a action.
+
+### 3. O contexto é uma projeção limitada, entregue como dado
+
+`context.data` contém somente os caminhos declarados, com a mesma estrutura da saída. O que não foi
+declarado não sai.
+
+Quando o JSON serializado passa de `maxContextChars`, o runtime reduz a projeção por etapas, até
+caber, e nunca em silêncio:
+
+1. Remove o último item da lista que tem mais itens, e repete. Registra em `omitted` o caminho e
+   quantos itens saíram.
+2. Com as listas vazias, encurta pela metade o texto mais longo, até o mínimo de 200 caracteres, e
+   repete. Registra o caminho em `omitted`.
+3. Se ainda não couber, remove campos inteiros, do último declarado em `context` para o primeiro,
+   e registra cada um em `omitted`.
+4. Marca `truncated: true`.
+
+O teto conta só os dados de `context`. O tipo, o id e o título vão no bloco fora dessa conta, e o
+título é sempre encurtado a no máximo 200 caracteres, com `…` e registro em `omitted`. Cada etapa
+remove alguma coisa, e a terceira chega, no limite, a um objeto vazio, que cabe em qualquer teto
+válido. Por isso o corte sempre termina.
+
+Um caminho declarado pode faltar na saída em execução, porque o runtime só valida a saída em
+desenvolvimento (`src/core/runtime.ts:907-912`). Nesse caso, a projeção omite o caminho, registra-o
+em `omitted` com o motivo `missing`, emite um aviso no log e não falha a leitura.
+
+A projeção é uma função pura do core, `projectAssistantContext(assistant, output)`, usada por
+`readResource` e exportada. Um host que recebe a saída da action por outro canal, como o MCP,
+aplica a mesma projeção sem reimplementá-la.
+
+O host entrega a projeção ao modelo como bloco de dado delimitado, numa mensagem de dado, e nunca
+no prompt de sistema. O bloco leva o tipo, o id, o título, os dados e, quando houver corte,
+`truncated` e `omitted`: o modelo precisa saber que o dado está incompleto para decidir chamar a
+action. Para hosts que usam o driver de IA do Opus, o pacote oferece a função que monta o bloco e
+neutraliza o delimitador dentro dos valores. O host pode usar o próprio formato, desde que cumpra a
+mesma regra.
+
+A projeção governa só o que o host entrega **por iniciativa própria**, como o dado do recurso que
+acompanha um turno de conversa vinculada. Quando e com que frequência entregar é decisão do host.
+A recomendação do Opus é reaproveitar a execução que já confere o acesso, em vez de executar a
+action de novo só para obter o contexto: cada execução de uma action com dado pessoal é uma marca
+de exposição. Quando o modelo chama a action dona como ferramenta, recebe a saída que o
+contrato declara, como em qualquer chamada. Filtrar a resposta pelo consumidor faria a mesma action
+devolver coisas diferentes para a tela e para a IA. Um campo que não deve chegar ao modelo em
+nenhuma hipótese pede outra decisão no contrato, e não uma projeção.
+
+**Dado pessoal.** A execução da action dona é marcada no registro da requisição como qualquer
+outra (ADR 0041). `context.personalData` repete a declaração da action para que o host marque a
+conversa: o Opus não conhece conversas.
+
+### 4. Projeções: manifest, ferramentas, MCP e Lente
+
+- **Manifest.** Cada action passa a projetar `ai` normalizado (`enabled`, `description`,
+  `destructive`, `requiresConfirmation`) e, quando houver, `assistant` com todos os campos. A
+  publicação para a IA entra no manifest junto, porque sem ela a Lente não consegue dizer o que a
+  IA alcança.
+- **`runtime.aiTools()`.** A ferramenta da action dona leva `metadata.assistant` com `resource`,
+  `skill`, `label`, `title`, `context` e `maxContextChars`. *Nota (2026-10-03):* o teto, já
+  resolvido, entrou na implementação para o host que projeta pelo MCP usar o mesmo valor; ver a
+  nota de implementação na seção 10.
+- **MCP.** O `ListTools` acrescenta `com.softize.opus/assistant` em `_meta`, com o mesmo conteúdo.
+  O host de IA conhece o assistente pelo catálogo que já consulta, sem configuração própria.
+- **Lente.** A estrutura de cada action passa a carregar `ai`, `effect`, `personalData` e
+  `assistant`. A página da action mostra se ela está publicada para a IA, se é dona de um tipo de
+  recurso, que procedimento o assistente segue e quais campos vão ao modelo. A mudança é feita no
+  repositório da Lente, com versão própria, lendo o manifest como hoje.
+
+### 5. O procedimento é referência por chave, conferida pelo consumidor
+
+`skill` é uma chave opaca para o Opus, em minúsculas com hífen (`review-customer`). O `opus check`
+confere a forma e a presença; não confere se o procedimento existe.
+
+Quem confere é o consumidor, onde tiver acesso às duas fontes: num teste que compare as
+declarações (o manifest versionado ou `runtime.assistants()`) com os procedimentos que o consumidor
+versiona, ou no turno, quando o host já tem o catálogo e o registro em mãos. A subida de um serviço
+não é um bom lugar: as duas fontes podem estar em serviços diferentes, e o catálogo pode exigir
+credencial. Na Grand Brasil, as declarações vivem no serviço principal, as Habilidades no serviço
+de IA, e o MCP interno só lista ferramentas com sessão e credencial de turno
+(`packages/agent-authority/src/staff-mcp.ts:95-109` dela).
+
+A Lente mostra a chave declarada. Mostrar se a chave resolve exige que o host informe esse estado
+à Lente, o que fica fora desta decisão.
+
+### 6. Acesso a recurso só por action
+
+Para o Opus, o princípio é: o recurso de um assistente é lido, e o acesso a ele é conferido,
+somente pela action dona. O SDK cumpre a sua parte nas seções 2 e 3.
+
+O Opus não enxerga as rotas HTTP que o consumidor registra por conta própria. O teste que impede
+uma rota de conferir acesso sem action é do consumidor. O `docs/protocol.md` registra o princípio e
+recomenda esse teste.
+
+### 7. O que o `opus check`, o `opus gen` e o `opus copy` cobram
+
+A regra `assistant-declaration` do `opus check` reprova:
+
+- `assistant` em action que não é `view`;
+- `assistant` com `ai: false` ou sem `ai`;
+- `assistant` sem `personalData` declarado;
+- `resource` fora de camelCase ou `skill` fora de minúsculas com hífen;
+- `label`, `title` ou `context` ausentes;
+- o mesmo `resource` em dois contratos, pelo valor literal, entre arquivos.
+
+O `opus gen`, que já converte a saída em JSON Schema (`bin/lib/gen-runner.mjs:399`), recusa gerar
+o manifest quando `title` ou um caminho de `context` não existem na saída, ou quando a entrada não
+tem `id` de texto como único campo obrigatório. Num campo anulável ou numa união (`anyOf` no JSON
+Schema), o caminho vale se existir em algum ramo que não seja `null`.
+
+O `register` do runtime recusa duas actions donas do mesmo `resource`, com
+`runtime.assistant_duplicate_resource`, e um `maxContextChars` fora do intervalo, com
+`runtime.assistant_context_limit_invalid`. Os erros desta decisão usam o prefixo
+`runtime.assistant_`.
+
+O `opus copy` passa a ler `assistant.label`.
+
+### 8. Relação com a Presentation
+
+`assistant.triggerLabel` da Presentation continua sendo a capacidade de interface: o botão no
+header e a divisão da superfície. A declaração da action é o comportamento do chat. As duas são
+independentes nesta decisão: o assistente existe também onde não há Presentation, como num drawer
+composto à mão ou no chat geral.
+
+### 9. O que fica fora
+
+- Endereço de navegação do recurso. É da interface do consumidor.
+- Persona, regras próprias de cada tipo e a forma de ativar o procedimento no turno. São do host.
+- Escrita. A declaração descreve a leitura; a escrita continua governada por `effect`, `ai` e pelo
+  host.
+
+### 10. As questões que ficaram para decisão
+
+A proposta deixou cinco questões para decidir antes da implementação. Em 2026-10-03, todas foram
+decididas como a proposta recomendava; cada item registra a questão, a decisão e o motivo.
+
+1. **Nomes finais.** *Decisão:* `assistant`, `resource`, `skill`, `label`, `title`, `context` e
+   `runtime.readResource`. `skill` acompanha o identificador técnico que os consumidores já usam;
+   para pessoas, a Grand Brasil continua dizendo Habilidade.
+2. **Teto do contexto.** *Decisão:* 4.000 caracteres por padrão, 1.000 no mínimo e 16.000 no
+   máximo (seções 1 e 3). Cabe o resumo de um cadastro e fica longe do teto de histórico que a
+   Grand Brasil usa (40.000).
+3. **Projeção nas respostas de ferramenta.** *Decisão:* não aplicar, pelos motivos da seção 3.
+4. **Rótulo do botão da Presentation.** *Decisão:* `triggerLabel` e `assistant.label` ficam
+   independentes (seção 8). Herdar o rótulo da action do corpo na Presentation, caso a repetição
+   apareça na prática, pede uma decisão própria.
+5. **Versão.** *Decisão:* minor, porque o campo é opcional e a regra só cobra quem declara.
+
+**Nota de implementação (2026-10-03).** A implementação preencheu os pontos que a decisão deixava em
+aberto assim:
+
+- **Projeção sob pedido.** `runtime.readResource` ganhou um quarto parâmetro opcional,
+  `{ context?: boolean }`. Sem ele, a leitura devolve só o descritor, que é o que a listagem de um
+  histórico usa, e resolve apenas o título (`resolveAssistantTitle`), sem serializar nem cortar a
+  saída; com `context: true`, devolve também a projeção. A execução da action e a autorização são as
+  mesmas nos dois casos. O aviso de título ausente vale sempre; o de caminho de `context` ausente,
+  só quando a projeção roda.
+- **Falha na projeção.** Uma saída que o JSON não representa (`BigInt`, referência circular) não
+  derruba a leitura com exceção: `readResource` registra o erro no log e devolve
+  `runtime.assistant_projection_failed` (categoria `internal`). A execução da action já foi
+  auditada.
+- **Tipo sem dona.** `runtime.assistant_resource_unknown` tem mensagem fixa; o tipo recebido vai em
+  `meta.resource`, para não ecoar entrada de fora no texto do erro.
+- **Registro.** Além do dono duplicado e do teto, o `register` recusa a forma inválida da
+  declaração com `runtime.assistant_declaration_invalid`: `assistant` fora de `view`, `ai` não
+  habilitado, `personalData` não declarado, `resource` ou `skill` fora do formato, `label`, `title`
+  ou `context` ausentes ou caminho com segmento vazio. Quem não roda o `opus check` no gate recebe a
+  mesma régua ao subir o serviço. A entrada `{ id }` continua conferida só pelo `opus gen`, que
+  enxerga o JSON Schema; o core segue sem dependência de schema.
+- **Teto nas projeções.** `aiTools()`, o `_meta` do MCP, o manifest e `runtime.assistants()` levam
+  a mesma forma, com `maxContextChars` já resolvido (4.000 quando não declarado), para o host que
+  aplica `projectAssistantContext` por outro canal usar o teto declarado. O `opus check` também reprova
+  `maxContextChars` literal fora de 1.000 a 16.000; um valor não literal fica para o registro.
+- **`omitted`.** Cada entrada é `{ path, reason, count? }`, com `reason` igual a `items` (itens
+  removidos do fim da lista, `count` diz quantos), `shortened`, `removed` ou `missing`. O caminho é
+  o da saída, sem índice de lista: em `removed` e `missing`, é o declarado (ou o do título); em
+  `items` e `shortened`, pode ficar abaixo do declarado quando o caminho declarado termina num
+  objeto ou numa lista. Um título ausente, nulo ou que não é texto nem número vira `title: null` e
+  entra em `omitted` como `missing`, com o aviso no log. O título passa por `toJSON` como na
+  serialização, para sair igual com e sem a projeção (uma data vira o texto ISO nos dois casos). O `opus gen` recusa `title` que não
+  resolve para texto ou número, fora de lista, em algum ramo não nulo.
+- **Custo do corte.** As etapas 1 e 2 escolhem a maior lista e o texto mais longo por fila de
+  prioridade, sem varrer a projeção a cada passo: o custo cresce com o tamanho da saída. Um teste
+  roda os cenários num processo filho com prazo, porque o laço é síncrono e o prazo do teste não o
+  interromperia.
+- **Segmentos reservados.** `__proto__`, `constructor` e `prototype` não são aceitos como segmento
+  de `title` ou `context` no registro, no `opus gen` e, quando literais, no `opus check`; a projeção
+  grava as chaves como propriedades próprias.
+- **Caminhos sobrepostos.** Um caminho coberto por outro declarado, como `leads.totalCount` junto de
+  `leads`, é ignorado na projeção, porque o mais curto já leva o valor inteiro.
+- **Bloco ao modelo.** A função é `resourceDataBlock`, de `@softize/opus/ai`. O bloco é uma linha de
+  JSON entre `<resource-data>` e `</resource-data>` (a etiqueta pode ser trocada por outra em
+  minúsculas com hífen). Saem como escapes `\u`, que o JSON lê como o mesmo texto: `<` e `>`; os
+  sinais que a normalização NFKC transforma neles; os confusáveis cujo esqueleto contém `<` ou `>`,
+  derivados do confusables.txt do Unicode (UTS #39, versão de 2026-08-06); os colchetes angulares
+  de outros blocos; os caracteres de controle (C0, DEL, C1 e NEL); os de formatação
+  invisíveis; os seletores de variação; os preenchimentos do hangul; os separadores de linha e
+  parágrafo; e os espaços que não são o espaço comum. `truncated` e `omitted` entram quando houve
+  corte ou quando faltou algum caminho.
+- **`opus gen`.** Um campo sem forma declarada na saída (`z.unknown()`, `z.any()`) aceita qualquer
+  caminho abaixo dele, porque não há o que conferir. Um schema que não pôde ser convertido em JSON
+  Schema recusa o manifest. Na entrada, além de `id`, campos opcionais sem valor padrão também são
+  aceitos: a decisão só recusa outro campo obrigatório.
+- **`label`.** É texto simples, não `I18nRef`, como o `triggerLabel` da Presentation. O `opus copy`
+  o inventaria com o papel `title`, porque ele nomeia o assistente na superfície do chat.
+- **Aviso de caminho ausente.** O log usa o código `runtime.assistant_path_missing`, com a action,
+  o recurso e os caminhos.
+- **Caminho que termina num contêiner.** Um caminho de `context` que termina num objeto ou numa
+  lista projeta tudo o que está abaixo dele, inclusive campos que a saída ganhar depois. O consumidor
+  que mantém uma lista de campos proibidos precisa conferir os descendentes, e não só o último
+  segmento do caminho. Para isso, `@softize/opus/assistant-schema` exporta
+  `assistantContextLeaves(output, context)`: a partir do JSON Schema da saída, como o manifest o
+  traz, devolve por caminho os campos folha alcançados e os pontos sem forma declarada ou em que um
+  `$ref` volta a si mesmo, por onde qualquer campo pode passar. O subpath publica tipos
+  (`assistant-schema.d.mts`) para um teste em TypeScript estrito.
+
+## Consequências
+
+- A action dona passa a ser a fonte única de leitura, acesso, procedimento e dado ao modelo para um
+  tipo de recurso. O consumidor troca tabelas no host, montagem na tela e `if` por tipo por uma
+  declaração e duas leituras do runtime.
+- O manifest cresce com `ai` e `assistant`. Projetos que versionam o manifest regeneram com
+  `opus gen` na atualização.
+- A Lente passa a mostrar, por action, o que a IA alcança e o que cada assistente entrega ao
+  modelo. Depende de uma versão nova da Lente.
+- O campo é opcional e entra numa minor. A regra do `opus check` vale só para quem declara.
+- A conferência de acesso executa a action inteira. Uma action dona pesada fica cara para listar
+  conversas; o consumidor mede e, se preciso, escolhe uma `view` mais leve como dona.
+- A existência do procedimento continua fora do alcance do SDK. Uma chave errada só aparece no
+  teste do consumidor ou no turno.
+
+## Alternativas descartadas
+
+### Manter a política no host
+
+É o estado atual. Cada consumidor repete tabela de procedimentos, montagem de contexto e rota por
+tipo, e nada disso aparece no manifest nem na Lente.
+
+### Declarar dentro de `ai`
+
+`ai: { assistant: { ... } }` deixaria tudo que é de IA num lugar. Mas a declaração também define a
+action dona do recurso, usada para conferir acesso em telas e listagens que não são da IA, como o
+histórico de conversas. É o mesmo motivo que levou `effect` e `personalData` para fora de `ai` na
+ADR 0041.
+
+### Declarar na Presentation
+
+A Presentation é interface, e o recurso precisa do assistente também onde não há Presentation: num
+drawer composto pelo consumidor ou no chat geral, que não tem superfície.
+
+### Projeção por função
+
+`context: (output) => ...` seria mais flexível, mas não é serializável. Sem uma lista de caminhos,
+o manifest e a Lente não conseguem mostrar quais dados vão ao modelo, que é o objetivo da
+declaração.
+
+### Validar o procedimento no `opus check`
+
+O check é estático e o registro de procedimentos é dado de banco, diferente em cada ambiente.
+Reprovar ali exigiria acesso ao banco no gate ou uma cópia do registro no repositório.
+
+### Aplicar a projeção também às respostas de ferramenta
+
+Minimizaria o dado ao modelo, mas a mesma action devolveria coisas diferentes por consumidor, e os
+procedimentos que precisam da saída completa, como editar um relatório pela revisão lida,
+deixariam de funcionar.
+
+## Verificação
+
+- Testes do SDK:
+  - `assistant` numa action que não é `view`, sem `ai` ou sem `personalData` falha no `opus check`;
+  - dois contratos com o mesmo `resource` falham no `opus check` e no `register`;
+  - `opus gen` recusa `title` ou caminho de `context` ausentes na saída, aceita caminho que existe
+    num ramo não nulo de `anyOf` e recusa entrada sem `id` ou com outro campo obrigatório;
+  - `readResource` executa a action dona pelo `execute`: a autorização da action vale, o registro
+    de auditoria é gerado e a marca de dado pessoal aparece;
+  - `readResource` com tipo sem action dona devolve `runtime.assistant_resource_unknown` sem
+    executar nada;
+  - a projeção devolve só os caminhos declarados, inclusive dentro de listas, e `null` quando um
+    campo intermediário é nulo;
+  - um caminho ausente em execução é omitido com motivo `missing` e aviso no log, sem falhar;
+  - acima do teto, a projeção segue as etapas da seção 3 na ordem, marca `truncated`, lista o que
+    saiu em `omitted` e termina mesmo com o teto mínimo;
+  - um título acima de 200 caracteres é encurtado e registrado em `omitted`, sem entrar na conta do
+    teto;
+  - o bloco entregue ao modelo leva `truncated` e `omitted`, e a função de bloco neutraliza o
+    delimitador dentro dos valores;
+  - o manifest projeta `ai` e `assistant`; `aiTools()` e o `ListTools` do MCP levam a declaração;
+  - `opus copy` inventaria `assistant.label`.
+- Documentação e skills do pacote, no mesmo entregável:
+  - `docs/protocol.md` ganha o campo na definição de action (seção 2), o princípio da seção 6 desta
+    ADR e o verbete no glossário;
+  - a página de actions da documentação (`src/ui/docs/content/actions.md`) mostra o campo e a ordem
+    canônica com ele;
+  - as skills `create-opus-action` e `test-opus-action` (`registry/skills`) ensinam a declarar e a
+    testar o assistente.
+- Na Lente: a página de uma action com assistente mostra publicação para a IA, efeito, dado pessoal,
+  procedimento e campos enviados ao modelo.
+- Na Grand Brasil, a adoção (ADR 0111 dela) declara as quatro actions donas e troca a rota por tipo
+  pela leitura do runtime.

package/docs/protocol.md

@@ -135,6 +135,16 @@ type ViewAction<In, Out> = ActionBase<In, Out> & {
   kind: 'view'
   projection: string[]
   expand?:    Record<string, ExpandSpec>
+  assistant?: ActionAssistant           // torna a view a action dona do recurso (ADR 0053)
+}
+
+type ActionAssistant = {
+  resource:         string              // tipo de recurso, camelCase, único no runtime
+  skill:            string              // chave do procedimento da IA, minúsculas com hífen
+  label:            string              // nome do assistente para pessoas
+  title:            string              // caminho, na saída, do campo que nomeia o recurso
+  context:          string[]            // caminhos, na saída, do dado que pode ir ao modelo
+  maxContextChars?: number              // teto do JSON de context: padrão 4.000, de 1.000 a 16.000
 }
 ```
 
@@ -230,6 +240,47 @@ Output de search action é **sempre** `Paginated<Output>` (ver §6).
 **`view`**
 - `projection: string[]` — campos/relações sempre carregados (`['owner', 'company.address']`).
 - `expand?: Record<string, ExpandSpec>` — relações opt-in por request.
+- `assistant?: ActionAssistant` — declara o assistente do recurso que a view lê e a torna a
+  **action dona** desse tipo de recurso (ADR 0053). Ver "Assistente do recurso", abaixo.
+
+### Assistente do recurso
+
+Uma conversa sobre um recurso específico, como um cliente ou um relatório, precisa ler o recurso
+com a permissão de quem conversa, seguir o procedimento próprio daquele tipo e entregar ao modelo só
+o dado necessário. A action `view` que lê o recurso declara as três coisas em `assistant` (ADR 0053).
+
+- **Requisitos da action dona.** Ser `view`; ter `ai` habilitado; declarar `personalData`; ter
+  entrada em que `id`, do tipo texto, é o único campo obrigatório. Cada `resource` tem uma única
+  action dona no runtime. O registro recusa a forma inválida (`runtime.assistant_declaration_invalid`),
+  o teto fora do intervalo (`runtime.assistant_context_limit_invalid`) e o dono duplicado
+  (`runtime.assistant_duplicate_resource`); o `opus check` (regra `assistant-declaration`) e o
+  `opus gen` (caminhos e entrada contra o JSON Schema) cobram o mesmo antes da execução.
+- **Caminhos.** O ponto desce em objetos; um caminho que passa por uma lista vale para cada item;
+  um intermediário `null` aparece como `null`. Num campo anulável ou numa união, o `opus gen` aceita
+  o caminho que existe em algum ramo não nulo. Um caminho que termina num objeto ou numa lista leva
+  tudo abaixo dele (`assistantContextLeaves`, de `@softize/opus/assistant-schema`, lista o que cada
+  caminho alcança). `title` aponta para texto ou número, fora de lista.
+- **Leitura.** `runtime.readResource(resource, id, base, { context? })` executa a action dona com
+  `{ id }` pelo `execute`: autorização, loaders, auditoria, marca de dado pessoal e span são os da
+  action. Devolve `{ ok: true, resource: { kind, id, title, label, skill }, context?, meta }` ou o
+  erro da action; um tipo sem dona devolve `runtime.assistant_resource_unknown` sem executar nada.
+  `runtime.assistants()` lista as declarações com a action dona.
+- **Projeção.** `projectAssistantContext(assistant, output)`, função pura do core, devolve só os
+  caminhos declarados. Acima do teto, corta por etapas até caber: o último item da maior lista; com
+  as listas vazias, o texto mais longo pela metade, até 200 caracteres; por fim, campos inteiros, do
+  último declarado ao primeiro. Marca `truncated` e registra o que saiu em `omitted`. O título fica
+  fora do teto e é encurtado a 200 caracteres. Caminho ausente na saída vai a `omitted` com o motivo
+  `missing`, sem falhar a leitura.
+- **Entrega ao modelo.** O host entrega a projeção como bloco de dado delimitado, numa mensagem de
+  dado, nunca no prompt de sistema (`resourceDataBlock`, de `@softize/opus/ai`). A projeção governa
+  só o que o host entrega por iniciativa própria; quando o modelo chama a action dona como
+  ferramenta, recebe a saída completa do contrato.
+
+**Princípio: acesso a recurso só por action.** O recurso de um assistente é lido, e o acesso a ele é
+conferido, somente pela action dona. O SDK não oferece outro caminho: a declaração não exporta
+regra de acesso, consulta nem atalho que dispense a action. O Opus não enxerga as rotas HTTP que o
+consumidor registra por conta própria; recomenda-se que o consumidor mantenha um teste que reprove
+rota que leia tabela de recurso ou chame regra de acesso de domínio fora de uma action.
 
 ### Exemplos por kind
 
@@ -2279,6 +2330,9 @@ chamada, inclusive por IA e MCP.
 - **`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.
+- **`assistant`** — declaração, numa action `view`, do assistente do recurso que ela lê: tipo de recurso, chave do procedimento, nome, campo do título e caminhos do dado ao modelo. Ver §2 e ADR 0053.
+- **Action dona** — a única action `view` que declara `assistant` para um tipo de recurso; é por ela que o recurso é lido e que o acesso a ele é conferido. Ver §2.
+- **`runtime.readResource`** — lê um recurso pela action dona, pelo mesmo `execute` de qualquer chamada, e devolve o descritor e, quando pedida, a projeção limitada do dado ao modelo. Ver §2.
 - **`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.

package/docs/releasing.md

@@ -59,14 +59,20 @@ O token usado para publicar é exclusivamente o token do npm no `~/.npmrc` globa
 pra testar publicação seria a guarda atrapalhando quem está experimentando.
 
 **Gate de qualidade**: depois do bump e da materialização, mas antes de publicar, roda
-`pnpm typecheck` + `pnpm test` + `pnpm copy:check` + `base copy check` e **aborta a release
-se qualquer um falhar**. O Opus declara `@softize/base ^2.4.0` em `dependencies`, pois usa
+`pnpm typecheck` + `pnpm test` + `pnpm test:browser` + `pnpm copy:check` + `base copy check` e
+**aborta a release se qualquer um falhar**. O Opus declara `@softize/base ^2.4.0` em `dependencies`, pois usa
 suas APIs públicas de filesystem em runtime, e materializa os artefatos Base no próprio repo;
 a release não baixa uma política ad hoc. Como o
 Opus **ship source** (`.ts`, sem build), essa é a última barreira antes do tarball — sem ela,
 um `tsc` vermelho, inventário desatualizado ou violação da política vaza pro cliente. Emergência (evite):
 `pnpm release --skip-checks`.
 
+`pnpm test:browser` roda em Chromium real, pelo modo navegador do Vitest com Playwright, os testes
+que o `happy-dom` não reproduz com fidelidade, como o foco e o Tab da camada flutuante (ADR 0052).
+Ele fica fora do `pnpm test` para que o ciclo comum não dependa de navegador. O Chromium é o da
+revisão fixada pela versão exata do `playwright` nas devDependencies; se a estação não o tiver, o
+comando falha dizendo isso, e `pnpm exec playwright install chromium` o instala.
+
 O gate roda `pnpm test`, não `pnpm test:cov`: o threshold de 100% de cobertura em
 `vitest.config.ts` é uma meta aspiracional e **não** faz parte do gate de release. Uma release
 não é bloqueada por cobertura abaixo de 100%; a cobertura é acompanhada com `pnpm test:cov`.

package/docs/stacking-scale.md

@@ -0,0 +1,53 @@
+# Escala de empilhamento
+
+> **Status: decidido (out/2026).** As sobreposições do Opus ocupam quatro faixas de `z-index`,
+> definidas pela ADR 0052. Os valores são detalhe de implementação; a ordem entre as faixas é o
+> contrato.
+
+## Contexto
+
+Até a camada flutuante, toda sobreposição do Opus usava `z-50`: véu e conteúdo de Dialog e Drawer,
+Popover, Menu e Tooltip. A ordem no DOM desempatava, e o que abria depois ficava por cima. Isso
+bastava enquanto só existiam modais e sobreposições presas a um gatilho.
+
+A camada flutuante (`FloatingLayer`) precisa ficar acima de Dialog e Drawer e, ao mesmo tempo,
+abaixo dos diálogos de resposta obrigatória, que a cobrem com o véu (decisão 4 da seção 9 da ADR
+0052). A ordem no DOM não garante isso: o hospedeiro da camada é montado uma vez e continua no
+`body` enquanto modais abrem e fecham depois dele.
+
+## Decisão
+
+Do fundo para a frente:
+
+| Faixa                     | `z-index`     | Quem ocupa                                                                                     |
+| ------------------------- | ------------- | ---------------------------------------------------------------------------------------------- |
+| Conteúdo                  | `auto`        | A página.                                                                                      |
+| Modal                     | `50`          | Dialog, Drawer, seus véus e Popover, Menu e Tooltip abertos fora da camada.                    |
+| Camada flutuante          | `60`          | O hospedeiro `div[data-slot="floating-layer"]`.                                                |
+| Resposta obrigatória      | `70`          | Véu e conteúdo de `Dialog mode="alert"`, que também serve às confirmações do `DialogHost`.     |
+| Avisos                    | `999999999`   | O `Toaster`, com o valor do Sonner.                                                            |
+
+- Dentro de uma faixa, a ordem no DOM continua desempatando, como antes.
+- O hospedeiro da camada cria um contexto de empilhamento próprio. Popover, Menu, Tooltip, Dialog e
+  Drawer abertos de dentro dela são portados para o hospedeiro e mantêm o `z-50` lá dentro, acima
+  do painel que os abriu.
+- Popover, Menu e Tooltip abertos de dentro de um alerta herdam a faixa do alerta (`z-70`); sem
+  isso, ficariam por baixo do véu que o próprio alerta desenha.
+- Componente novo que abre uma sobreposição usa as faixas acima e lê o contêiner da camada; o
+  teste `tests/architecture/floating-layer.test.ts` cobra o contêiner de todo portal.
+- Um alerta em animação de saída deixa de receber clique (`pointer-events: none`). Sem isso, o véu
+  dele, ainda em `z-70`, cobriria por cerca de 150 ms o Dialog que a resposta abre na faixa de
+  baixo.
+
+## Consequências
+
+- Um consumidor que posiciona elementos próprios com `z-index` acima de `50` passa a competir com a
+  camada. Use a camada para o que precisa ficar acima dos modais, em vez de subir o `z-index`.
+- Um elemento do consumidor com `z-index` entre `51` e `69` ficava acima de um alerta, que estava em
+  `z-50`, e agora fica abaixo dele.
+- Uma sobreposição de outra biblioteca que fixa `z-50` e é aberta de dentro de um alerta fica abaixo
+  do véu do alerta, porque não lê a faixa que os primitives do Opus herdam. Suba a faixa dela para
+  `z-70` ou troque-a por um primitive do Opus.
+- Mudar um valor exige mudar todos os pontos que dependem dele: `overlayClasses` e o conteúdo em
+  `dialog.tsx` e `drawer.tsx`, o hospedeiro em `floating-layer.tsx` e a faixa do alerta em
+  `modal-layers.ts`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softize/opus",
-  "version": "25.0.0",
+  "version": "25.2.0",
   "description": "End-to-end action protocol for TypeScript. Single package with subpath exports (core + adapters).",
   "license": "MIT",
   "type": "module",
@@ -20,6 +20,10 @@
     "./introspect": {
       "default": "./bin/lib/introspect.mjs"
     },
+    "./assistant-schema": {
+      "types": "./bin/lib/assistant-schema.d.mts",
+      "default": "./bin/lib/assistant-schema.mjs"
+    },
     "./init": {
       "default": "./bin/lib/init.mjs"
     },
@@ -362,6 +366,7 @@
     "@opentelemetry/api": "^1.9.1",
     "@opentelemetry/context-async-hooks": "^2.10.0",
     "@opentelemetry/sdk-trace-base": "^2.10.0",
+    "@tailwindcss/vite": "^4.3.2",
     "@tanstack/react-query": "^5.62.0",
     "@testing-library/dom": "^10.4.0",
     "@testing-library/react": "^16.1.0",
@@ -371,6 +376,7 @@
     "@types/pg": "^8.11.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
+    "@vitest/browser": "2.1.9",
     "@vitest/coverage-v8": "^2.1.0",
     "better-sqlite3": "^11.0.0",
     "bullmq": "^5.0.0",
@@ -381,9 +387,11 @@
     "node-cron": "^3.0.3",
     "pg": "^8.13.0",
     "pino": "^9.5.0",
+    "playwright": "1.62.1",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "react-hook-form": "^7.54.0",
+    "tailwindcss": "^4.3.2",
     "tsx": "^4.19.0",
     "vite": "^6.0.0",
     "vitest": "^2.1.0",
@@ -400,6 +408,7 @@
     "copy:check": "node ./bin/cli.mjs copy --check",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
+    "test:browser": "vitest run --config vitest.browser.config.ts",
     "test:watch": "vitest",
     "test:cov": "vitest run --coverage",
     "registry:up": "npx -y verdaccio --config ~/.config/verdaccio/config.yaml",