@softize/opus 25.1.0 → 25.3.0

package/bin/lib/gen-manifest.mjs

@@ -55,6 +55,9 @@ function shapeAction(a) {
     automatable: a.automatable,
     effect: a.effect ?? null,
     personalData: a.personalData ?? null,
+    // ADR 0053: a publicação para a IA e, na action dona, o assistente do recurso.
+    ai: a.ai ?? { enabled: false, description: null, destructive: false, requiresConfirmation: false },
+    ...(a.assistant !== undefined && a.assistant !== null ? { assistant: a.assistant } : {}),
     internal: a.internal,
     successStatus: a.successStatus,
     input: a.input,
@@ -77,6 +80,7 @@ function shapeAction(a) {
     out.paginate = a.paginate;
     out.text = a.text;
     out.periods = a.periods;
+    if (a.grouping !== undefined) out.grouping = a.grouping;
   }
   if (a.kind === "view") {
     out.projection = a.projection ?? [];

package/bin/lib/gen-runner.mjs

@@ -43,7 +43,7 @@
  *       input: JSONSchema,                    // zod-to-json-schema
  *       output: JSONSchema,                   // zod-to-json-schema
  *       fields?: Record<string, FieldSpecSerialized>,
- *       filters?, sort?, paginate?, text?, periods?,  // search
+ *       filters?, sort?, paginate?, text?, periods?, grouping?,  // list
  *       projection?, expand?,                          // view
  *       background?: boolean,
  *       emits?: string[],
@@ -53,6 +53,8 @@
  *       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
+ *       ai: { enabled, description, destructive, requiresConfirmation }, // ADR 0053
+ *       assistant?: { resource, skill, label, title, context, maxContextChars }, // view dona
  *       internal?: boolean,
  *       rateLimit?: { window, max },
  *       confirm?: ConfirmSpec,
@@ -67,6 +69,7 @@
 
 import path from "node:path";
 import { pathToFileURL, fileURLToPath } from "node:url";
+import { assistantSchemaIssues, serializeAiConfig } from "./assistant-schema.mjs";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -90,7 +93,7 @@ async function main() {
   const opusCoreUrl = pathToFileURL(
     path.join(PACKAGE_ROOT, "src", "core", "index.ts"),
   ).href;
-  const { flattenDomain, domainPurges, declaredJsonSchema } = await import(opusCoreUrl);
+  const { flattenDomain, domainPurges, declaredJsonSchema, publicAssistant } = await import(opusCoreUrl);
 
   const opusSeedUrl = pathToFileURL(
     path.join(PACKAGE_ROOT, "src", "seed", "index.ts"),
@@ -138,6 +141,7 @@ async function main() {
   const ctx = {
     flattenDomain,
     domainPurges,
+    publicAssistant,
     // Standard Schema que declara o próprio JSON Schema (ADR 0051) dispensa o zod.
     toJsonSchema: (schema) =>
       declaredJsonSchema(schema, { target: "openapi-3.0" }) ??
@@ -393,6 +397,8 @@ function serializeAction(action, ctx) {
     // 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,
+    // ADR 0053: a publicação para a IA entra no manifest, e a action dona, o assistente.
+    ai: serializeAiConfig(action.ai),
     internal: action.internal === true,
     successStatus: action.successStatus,
     input: safeToJsonSchema(action.input, ctx),
@@ -427,6 +433,7 @@ function serializeAction(action, ctx) {
     base.paginate = action.paginate ?? null;
     base.text = action.text ?? null;
     base.periods = Array.isArray(action.periods) ? action.periods : [];
+    if (action.grouping !== undefined) base.grouping = action.grouping;
   }
 
   if (action.kind === "view") {
@@ -434,6 +441,20 @@ function serializeAction(action, ctx) {
     base.expand = action.expand ?? null;
   }
 
+  if (action.kind === "view" && action.assistant !== undefined && action.assistant !== null) {
+    const issues = assistantSchemaIssues({
+      assistant: action.assistant,
+      input: base.input,
+      output: base.output,
+    });
+    if (issues.length > 0) {
+      throw declarationError(
+        `O assistente da action "${action.name}" não confere com o contrato (ADR 0053): ${issues.join("; ")}.`,
+      );
+    }
+    base.assistant = ctx.publicAssistant(action.assistant);
+  }
+
   return base;
 }
 
@@ -605,6 +626,14 @@ function emitError(message) {
   process.exit(1);
 }
 
+/** Erro de declaração do consumidor: a mensagem basta, sem a pilha do runner. */
+function declarationError(message) {
+  const err = new Error(message);
+  err.name = "OpusDeclarationError";
+  return err;
+}
+
 main().catch((err) => {
+  if (err?.name === "OpusDeclarationError") return emitError(err.message);
   emitError(`runner crash: ${err.stack ?? err.message ?? String(err)}`);
 });

package/bin/lib/gen-stubs.mjs

@@ -149,6 +149,9 @@ function renderActionStub(action) {
       const filters = stripNullsFromFields(action.filters)
       lines.push(`  filters: ${formatObjectLiteral(filters, '  ')},`)
     }
+    if (action.grouping && Array.isArray(action.grouping.fields)) {
+      lines.push(`  grouping: ${JSON.stringify(action.grouping)},`)
+    }
   }
   if (Array.isArray(action.invalidates) && action.invalidates.length > 0) {
     lines.push(`  invalidates: ${JSON.stringify(action.invalidates)},`)

package/bin/lib/mcp.mjs

@@ -42,7 +42,7 @@ export function buildServer() {
   server.registerTool(
     'opus_check',
     {
-      description: 'Valida as convenções das actions (régua) — defineAction e o split defineContract+bindAction: naming, kind, ordem dos campos, export, requires-sem-authorize, ignored-by-kind, soft-delete-retention. Retorna findings.',
+      description: 'Valida as convenções das actions (régua) — defineAction e o split defineContract+bindAction: naming, kind, ordem dos campos, export, requires-sem-authorize, ignored-by-kind, assistant-declaration, soft-delete-retention. Retorna findings.',
       inputSchema: { dir: z.string().optional() },
     },
     async ({ dir }) => asText(await scanDir(dirOf(dir))),

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/adr/0054-action-list-grouping-is-a-declared-server-cut.md

@@ -0,0 +1,82 @@
+# ADR 0054 — Agrupamento da ActionList é um recorte declarado e consultado no servidor
+
+- **Status:** aceita.
+- **Data:** 2026-10-03.
+- **Relacionadas:** ADR 0013 (Presentation orientada a action) e ADR 0024 (preenchimento das
+  regiões de lista).
+
+## Contexto
+
+Listagens operacionais precisam, em alguns casos, comparar conjuntos dentro do mesmo recorte. A
+fila de eventos da Grand Brasil é o primeiro caso: a pessoa quer reunir os eventos por status sem
+perder busca, filtros, ordenação, contagens ou paginação.
+
+Agrupar apenas os itens carregados criaria uma representação falsa. Uma página de cinquenta itens
+não permite concluir quantos registros existem em cada grupo, e trocar de página faria grupos
+sumirem ou mudarem de tamanho. Acrescentar um envelope agregado ao protocolo resolveria isso com
+uma consulta, mas obrigaria todo handler e adapter a aprender uma segunda forma de resposta antes de
+existir evidência de que o custo compensa.
+
+O campo também não pode ser inferido de toda coluna ou filtro. Texto livre e lookup podem ter
+cardinalidade alta, data e número exigem faixas, e nem toda dimensão fechada faz sentido como
+organização da lista. A decisão precisa continuar no contrato de produto.
+
+## Decisão
+
+### 1. A action declara as dimensões permitidas
+
+Uma `ListAction` pode declarar:
+
+```ts
+grouping: {
+  fields: ['status', 'stage'],
+}
+```
+
+Cada nome referencia um filtro `select` com opções `static` ou `dictionary`. O controle do filtro
+pode aceitar uma ou várias opções; cada consulta de grupo envia um único valor na forma esperada
+pelo filtro. A declaração não define agrupamento inicial: a lista continua plana até a pessoa
+escolher “Agrupar por” em **Exibição**. O estado usa `groupBy` e a URL usa `group=<campo>`.
+
+O Opus rejeita dimensões ausentes, filtros de outro tipo, lookups, conjuntos estáticos sem opções
+fechadas e actions sem `paginate: 'offset'`. A interface oferece apenas dicionários resolvidos com
+até doze opções por dimensão; acima disso, a declaração não é adequada para agrupamento operacional.
+
+### 2. Cada grupo é uma consulta da mesma ListAction
+
+O agrupamento preserva o input base, a busca, o período, os demais filtros e a ordenação. Para cada
+opção da dimensão, o Opus executa a mesma action com o valor do grupo aplicado ao filtro. Um filtro
+já aplicado à dimensão restringe quais grupos aparecem; não é removido nem reinterpretado.
+
+Cada resposta precisa devolver `total`. A ausência desse dado vira o estado de erro da lista, sem
+lançar uma exceção durante o render. Esse total nomeia o grupo e governa sua paginação. O primeiro
+recorte usa o limite da lista; **Carregar mais** busca a página seguinte daquele grupo e acrescenta
+os itens, sem reiniciar os demais. A invalidação ou a atualização manual refaz todas as consultas.
+
+Essa primeira implementação aceita o custo de até doze consultas em paralelo. Um envelope de
+facetas ou uma action agregada só será introduzido quando medição real justificar outra fronteira.
+
+### 3. O agrupamento pertence à tabela
+
+A tabela mantém um único cabeçalho e abre um `tbody` por grupo. O cabeçalho do grupo é recolhível,
+expõe `aria-expanded`, apresenta o valor pelo dicionário quando houver e mostra a contagem correta,
+inclusive zero. O agrupamento não se aplica a `children` nem a views alternativas; ao sair da tabela,
+os dados voltam à consulta plana.
+
+Busca, filtros e período são aplicados antes do agrupamento; ordenação vale dentro de cada grupo. A
+seleção em lote cobre os itens carregados dos grupos abertos. Recolher um grupo remove da seleção os
+itens dele, para nenhuma ação operar sobre linhas invisíveis.
+
+Se uma consulta falhar, a lista apresenta o erro padrão e permite refazer o conjunto. Se todos os
+totais forem zero, há um único estado vazio. Não existe paginador global enquanto o agrupamento está
+ativo; o rodapé mostra apenas a soma dos totais.
+
+## Consequências
+
+- O contrato distingue capacidade de agrupamento de uma seleção corrente.
+- Contagens e páginas continuam autoritativas no servidor; não há agrupamento parcial silencioso.
+- O número de requisições cresce com as opções da dimensão, de forma explícita e limitada.
+- O primeiro consumidor deve testar que a soma dos totais agrupados coincide com o total da lista
+  plana para o mesmo recorte.
+- Uma futura otimização de protocolo pode preservar `grouping` e `groupBy`, trocando apenas como os
+  dados chegam ao cliente.