@softize/opus 25.1.0 → 25.3.0

package/CHANGELOG.md

@@ -7,6 +7,72 @@ Depois de qualquer bump, rode os gates (`typecheck` · `test` · `opus check` ·
 `opus copy --check` · `base copy check` · `manifest:check`) — eles apontam o que a
 mudança cobra do seu código.
 
+## 25.3.0 — 2026-10-05
+
+`ListAction.grouping` declara dimensões fechadas pelas quais a `ActionList` pode agrupar a tabela.
+Cada dimensão referencia um filtro `select` com até 12 opções estáticas ou de dicionário, e a
+action precisa usar `paginate: 'offset'` e devolver `total`. A pessoa escolhe o agrupamento em
+**Exibição**; cada grupo consulta o servidor separadamente, pode ser recolhido e carrega páginas
+adicionais sem descartar as anteriores. O agrupamento não altera views alternativas nem o modo de
+composição por `children`.
+
+O manifest e os stubs passam a projetar `grouping`. `ActionListState` e os helpers de URL preservam
+a dimensão em `group`; dimensões desconhecidas são ignoradas. A implementação das consultas por
+grupo permanece interna à `ActionList`, sem introduzir um hook público adicional.
+
+`useListAction(action, input, { enabled })` pode suspender a consulta declarativa sem desmontar o
+hook. O padrão é `true`; a `ActionList` usa essa opção internamente ao alternar entre a consulta
+plana e as consultas agrupadas.
+
+## 25.2.0 — 2026-10-03
+
+Uma action `view` pode declarar o assistente do recurso que ela lê (ADR 0053). Com isso, a conversa
+especializada num cliente, num relatório ou num pedido passa a ler o recurso, conferir o acesso,
+saber o procedimento da IA e escolher o dado ao modelo a partir de uma declaração só, no contrato:
+
+```ts
+ai: true,
+assistant: {
+  resource: 'customer',
+  skill: 'review-customer',
+  label: 'Assistente do cliente',
+  title: 'name',
+  context: ['kind', 'stage', 'leads.totalCount'],
+},
+```
+
+A action que declara passa a ser a action dona daquele tipo de recurso. Ela precisa ser `view`,
+estar publicada para a IA, declarar `personalData` e receber só `{ id }`.
+
+- `runtime.readResource(resource, id, base, { context })` executa a action dona pelo mesmo
+  `execute` de qualquer chamada, com a autorização, a auditoria e a marca de dado pessoal dela, e
+  devolve o descritor (`kind`, `id`, `title`, `label`, `skill`) e, com `context: true`, a projeção
+  limitada do dado. Um tipo sem dona devolve `runtime.assistant_resource_unknown` sem executar nada.
+- `runtime.assistants()` lista as declarações com a action dona, para o produto montar rotas sem
+  lista paralela e conferir num teste que cada `skill` existe no registro dele.
+- `projectAssistantContext(assistant, output)` devolve só os caminhos declarados e, acima do teto
+  (4.000 caracteres por padrão, de 1.000 a 16.000 em `maxContextChars`), corta por etapas até
+  caber, marcando `truncated` e listando o que saiu em `omitted`. Caminho ausente na saída é
+  omitido com o motivo `missing` e gera aviso no log, sem falhar a leitura.
+- `resourceDataBlock`, de `@softize/opus/ai`, monta o bloco delimitado que o host entrega ao modelo
+  numa mensagem de dado, com os escapes que impedem um valor de fechar o delimitador.
+- `runtime.aiTools()` leva `metadata.assistant`, e o `ListTools` do MCP publica
+  `com.softize.opus/assistant` em `_meta`.
+- O registro recusa a declaração inválida (`runtime.assistant_declaration_invalid`), o teto fora do
+  intervalo (`runtime.assistant_context_limit_invalid`) e duas donas do mesmo recurso
+  (`runtime.assistant_duplicate_resource`). O `opus check` ganha a regra `assistant-declaration`, o
+  `opus gen` confere `title`, `context` e a entrada contra os schemas, e o `opus copy` inventaria
+  `assistant.label`.
+- `@softize/opus/assistant-schema`, com tipos, exporta `assistantContextLeaves(output, context)`,
+  que lista, a partir do JSON Schema da saída no manifest, os campos folha que cada caminho de
+  `context` leva ao modelo. Um caminho que termina num objeto ou numa lista leva tudo abaixo dele; use a função num
+  teste para garantir que nenhum campo pessoal chega ao modelo por esse caminho.
+
+O manifest passa a projetar, em toda action, a publicação para a IA em `ai` (`enabled`,
+`description`, `destructive`, `requiresConfirmation`) e, na action dona, `assistant`. Se o seu
+projeto versiona o manifest, rode `opus gen` depois da atualização: sem isso, a conferência de
+frescor do manifest acusa a diferença. Nada muda para quem não declara assistente.
+
 ## 25.1.0 — 2026-10-03
 
 `FloatingLayer`, de `@softize/opus/ui/react`, é uma camada que continua utilizável por cima de

package/bin/cli.mjs

@@ -426,6 +426,11 @@ Regras das actions:
                             binding (o join contrato↔bind é cross-file)
   ignored-by-kind         — \`emits\` ou \`background\` em action list/view: o runtime
                             e o manifest só os aplicam em simple e form
+  assistant-declaration   — o assistente do recurso (ADR 0053): só em view, com \`ai\`
+                            habilitado, \`personalData\` declarado, \`resource\` em camelCase,
+                            \`skill\` em minúsculas com hífen, \`label\`, \`title\` e
+                            \`context\` presentes e \`maxContextChars\`, quando literal,
+                            de 1.000 a 16.000; o mesmo \`resource\` em duas actions reprova
 
 Regras da UI (@softize/opus/ui):
   ui-structure            — anatomia pública das superfícies compostas (ADR 0005):

package/bin/lib/assistant-schema.d.mts

@@ -0,0 +1,55 @@
+/**
+ * Tipos de `@softize/opus/assistant-schema` (ADR 0053): a conferência do assistente do recurso
+ * contra o JSON Schema da action, como o manifest o traz. A implementação é `assistant-schema.mjs`.
+ */
+
+/** Um JSON Schema como o `opus gen` o projeta no manifest. */
+export type JsonSchema = Record<string, unknown>
+
+/** Os campos que um caminho de `context` leva ao modelo. */
+export interface AssistantContextLeaves {
+  /** O caminho declarado em `context`. */
+  path: string
+  /** Os campos folha alcançados, com ponto e sem índice de lista; `*` marca a chave de um mapa. */
+  leaves: string[]
+  /**
+   * Pontos em que o schema não declara forma ou volta a si mesmo por `$ref`: qualquer campo abaixo
+   * deles pode ir ao modelo, e a conferência não alcança.
+   */
+  open: string[]
+}
+
+/**
+ * Os campos folha que cada caminho de `context` leva ao modelo, a partir do JSON Schema da saída.
+ * Serve a um teste do consumidor que reprova campo pessoal alcançado por um caminho que termina
+ * num objeto ou numa lista.
+ */
+export function assistantContextLeaves(
+  output: JsonSchema,
+  context: readonly string[],
+  root?: JsonSchema,
+): AssistantContextLeaves[]
+
+/** O caminho existe em algum ramo não nulo do schema; listas são atravessadas. */
+export function schemaHasPath(schema: JsonSchema, segments: readonly string[], root?: JsonSchema): boolean
+
+/** O título resolve para texto ou número, fora de lista, em algum ramo não nulo. */
+export function schemaTitleIsText(schema: JsonSchema, segments: readonly string[], root?: JsonSchema): boolean
+
+/**
+ * Os problemas do assistente diante dos schemas de entrada e de saída, como frases. Lista vazia
+ * quando a declaração confere.
+ */
+export function assistantSchemaIssues(args: {
+  assistant: { title?: unknown; context?: unknown }
+  input: unknown
+  output: unknown
+}): string[]
+
+/** O `ai` de uma action normalizado como o manifest o projeta. */
+export function serializeAiConfig(ai: unknown): {
+  enabled: boolean
+  description: string | null
+  destructive: boolean
+  requiresConfirmation: boolean
+}

package/bin/lib/assistant-schema.mjs

@@ -0,0 +1,286 @@
+/**
+ * assistant-schema — confere o assistente do recurso (ADR 0053) contra o JSON Schema da action,
+ * no `opus gen`: `title` e cada caminho de `context` precisam existir na saída, e a entrada precisa
+ * ser um objeto em que `id`, do tipo texto, é o único campo obrigatório.
+ *
+ * Num campo anulável ou numa união (`anyOf`, `oneOf`, `allOf`), o caminho vale se existir em algum
+ * ramo que não seja `null`. Uma lista é atravessada: o caminho continua nos itens. Um schema sem
+ * forma declarada (`{}`, de `z.unknown()` ou `z.any()`) aceita qualquer caminho abaixo dele, porque
+ * não há o que conferir.
+ */
+
+const COMBINATORS = ["anyOf", "oneOf", "allOf"];
+const STRUCTURE_KEYS = ["type", "properties", "items", "additionalProperties", "enum", "const"];
+const MAX_DEPTH = 64;
+// Segmentos que mexem no protótipo de um objeto JavaScript; o registro do runtime também os recusa.
+const RESERVED_SEGMENTS = new Set(["__proto__", "constructor", "prototype"]);
+
+function reservedSegments(path) {
+  return typeof path === "string" ? path.split(".").filter((segment) => RESERVED_SEGMENTS.has(segment)) : [];
+}
+
+function resolveRef(root, ref) {
+  if (!ref.startsWith("#/")) return undefined;
+  let node = root;
+  for (const raw of ref.slice(2).split("/")) {
+    const key = raw.replace(/~1/g, "/").replace(/~0/g, "~");
+    if (node === null || typeof node !== "object" || !Object.hasOwn(node, key)) return undefined;
+    node = node[key];
+  }
+  return node;
+}
+
+function isNullOnly(schema) {
+  if (schema.type === "null") return true;
+  if (Array.isArray(schema.type) && schema.type.every((type) => type === "null")) return true;
+  // O alvo OpenAPI 3.0 do zod-to-json-schema escreve o ramo nulo como `{ enum: ['null'], nullable: true }`.
+  return (
+    Array.isArray(schema.enum) &&
+    schema.enum.length > 0 &&
+    schema.enum.every((value) => value === null || value === "null") &&
+    (schema.nullable === true || schema.enum.includes(null))
+  );
+}
+
+const NO_REFS = new Set();
+/** Marca o ponto em que um `$ref` volta a um schema que já está no caminho atual. */
+const CYCLE = Object.freeze({ cycle: true });
+
+/**
+ * Os ramos concretos e não nulos de um schema, com `$ref` e combinadores expandidos. Cada ramo traz
+ * os `$ref` percorridos no caminho atual; um `$ref` que se repete ali vira `CYCLE`, em vez de
+ * expandir de novo.
+ */
+function expand(schema, root, active = NO_REFS, depth = 0) {
+  if (schema === null || typeof schema !== "object" || depth > MAX_DEPTH) return [];
+  if (typeof schema.$ref === "string") {
+    if (active.has(schema.$ref)) return [{ schema: CYCLE, active }];
+    const target = resolveRef(root, schema.$ref);
+    return target === undefined ? [] : expand(target, root, new Set([...active, schema.$ref]), depth + 1);
+  }
+  const nested = COMBINATORS.flatMap((key) =>
+    Array.isArray(schema[key]) ? schema[key].flatMap((branch) => expand(branch, root, active, depth + 1)) : [],
+  );
+  const hasOwnStructure = STRUCTURE_KEYS.some((key) => Object.hasOwn(schema, key));
+  const combined = COMBINATORS.some((key) => Array.isArray(schema[key]));
+  if (combined && !hasOwnStructure) return nested;
+  if (isNullOnly(schema)) return nested;
+  return [{ schema, active }, ...nested];
+}
+
+/** Os ramos sem os ciclos, para quem só olha o tipo do próprio nó. */
+function branches(schema, root) {
+  return expand(schema, root).flatMap(({ schema: branch }) => (branch === CYCLE ? [] : [branch]));
+}
+
+function isOpen(schema) {
+  return (
+    !Object.hasOwn(schema, "$ref") &&
+    !STRUCTURE_KEYS.some((key) => Object.hasOwn(schema, key)) &&
+    !COMBINATORS.some((key) => Object.hasOwn(schema, key))
+  );
+}
+
+function isArraySchema(schema) {
+  return schema.type === "array" || (Array.isArray(schema.type) && schema.type.includes("array")) || Object.hasOwn(schema, "items");
+}
+
+/**
+ * Os schemas alcançados por `segments` em todos os ramos não nulos. Um schema sem forma alcança
+ * qualquer caminho abaixo dele e entra como está. Com `throughLists`, uma lista é atravessada. Um
+ * ciclo de `$ref` sem avançar no caminho (por lista ou união) não leva a lugar nenhum; ao descer
+ * por um campo, o caminho avança, e o mesmo `$ref` pode voltar, como numa árvore.
+ */
+function collectTargets(schema, segments, root, throughLists, out, active = NO_REFS, depth = 0) {
+  if (depth > MAX_DEPTH) return;
+  if (segments.length === 0) {
+    out.push(schema);
+    return;
+  }
+  for (const { schema: branch, active: refs } of expand(schema, root, active)) {
+    if (branch === CYCLE) continue;
+    if (isOpen(branch)) {
+      out.push(branch);
+      continue;
+    }
+    if (isArraySchema(branch)) {
+      if (!throughLists) continue;
+      const items = Array.isArray(branch.items) ? branch.items : [branch.items];
+      for (const item of items) {
+        if (item !== undefined) collectTargets(item, segments, root, throughLists, out, refs, depth + 1);
+      }
+      continue;
+    }
+    const [head, ...rest] = segments;
+    const properties = branch.properties;
+    if (properties !== null && typeof properties === "object" && Object.hasOwn(properties, head)) {
+      collectTargets(properties[head], rest, root, throughLists, out, NO_REFS, depth + 1);
+    }
+    const additional = branch.additionalProperties;
+    if (additional !== null && typeof additional === "object") {
+      collectTargets(additional, rest, root, throughLists, out, NO_REFS, depth + 1);
+    }
+  }
+}
+
+/** O caminho `segments` existe em algum ramo não nulo de `schema`. */
+export function schemaHasPath(schema, segments, root = schema) {
+  const targets = [];
+  collectTargets(schema, segments, root, true, targets);
+  return targets.length > 0;
+}
+
+const TITLE_TYPES = new Set(["string", "number", "integer"]);
+
+/**
+ * O título resolve para texto ou número em algum ramo não nulo, sem atravessar lista: é o que o
+ * runtime consegue mostrar como nome do recurso.
+ */
+export function schemaTitleIsText(schema, segments, root = schema) {
+  const targets = [];
+  collectTargets(schema, segments, root, false, targets);
+  return targets.some((target) =>
+    isOpen(target) ||
+    branches(target, root).some((branch) => {
+      if (isOpen(branch)) return true;
+      const types = Array.isArray(branch.type) ? branch.type : [branch.type];
+      return types.some((type) => TITLE_TYPES.has(type));
+    }),
+  );
+}
+
+/**
+ * As folhas abaixo de `schema`. Um `$ref` que volta a um schema já no caminho atual (uma estrutura
+ * recursiva) entra em `open` naquele ponto: abaixo dele, qualquer profundidade pode chegar ao modelo.
+ */
+function collectLeaves(schema, prefix, root, leaves, open, active = NO_REFS, depth = 0) {
+  if (depth > MAX_DEPTH) {
+    open.add(prefix);
+    return;
+  }
+  for (const { schema: branch, active: refs } of expand(schema, root, active)) {
+    if (branch === CYCLE || isOpen(branch)) {
+      open.add(prefix);
+      continue;
+    }
+    if (isArraySchema(branch)) {
+      const items = Array.isArray(branch.items) ? branch.items : [branch.items];
+      for (const item of items) if (item !== undefined) collectLeaves(item, prefix, root, leaves, open, refs, depth + 1);
+      continue;
+    }
+    const properties = branch.properties;
+    const hasProperties = properties !== null && typeof properties === "object" && Object.keys(properties).length > 0;
+    if (hasProperties) {
+      for (const [key, child] of Object.entries(properties)) {
+        collectLeaves(child, `${prefix}.${key}`, root, leaves, open, refs, depth + 1);
+      }
+    }
+    const additional = branch.additionalProperties;
+    if (additional !== null && typeof additional === "object") {
+      collectLeaves(additional, `${prefix}.*`, root, leaves, open, refs, depth + 1);
+    }
+    if (!hasProperties && !(additional !== null && typeof additional === "object")) leaves.add(prefix);
+  }
+}
+
+/**
+ * Os campos folha que cada caminho de `context` leva ao modelo, segundo o JSON Schema da saída
+ * (ADR 0053). Um caminho que termina num objeto ou numa lista projeta tudo abaixo dele; esta função
+ * lista o que é, para o consumidor conferir num teste, por exemplo, que nenhum campo pessoal chega
+ * ao modelo por um caminho que termina num contêiner.
+ *
+ * - `leaves`: caminhos das folhas, com ponto e sem índice de lista; `*` marca a chave de um mapa;
+ * - `open`: pontos em que o schema não declara forma (`z.unknown()`, `z.any()`) ou volta a si mesmo
+ *   por `$ref`: qualquer campo abaixo deles pode ir ao modelo, e a conferência não alcança.
+ */
+export function assistantContextLeaves(output, context, root = output) {
+  return context.map((path) => {
+    const targets = [];
+    collectTargets(output, path.split("."), root, true, targets);
+    const leaves = new Set();
+    const open = new Set();
+    for (const target of targets) collectLeaves(target, path, root, leaves, open);
+    return { path, leaves: [...leaves].sort(), open: [...open].sort() };
+  });
+}
+
+function isText(schema, root) {
+  return branches(schema, root).some(
+    (branch) => branch.type === "string" || (Array.isArray(branch.type) && branch.type.includes("string")),
+  );
+}
+
+function unserializable(schema) {
+  return schema === null || schema === undefined || schema.__unserializable === true;
+}
+
+/**
+ * Os problemas do assistente de uma action diante dos JSON Schemas de entrada e de saída, como
+ * frases. Lista vazia quando a declaração cabe nos schemas.
+ */
+export function assistantSchemaIssues({ assistant, input, output }) {
+  const issues = [];
+  if (unserializable(input)) {
+    issues.push("o schema de entrada não pôde ser convertido em JSON Schema para conferir o `id`");
+  } else {
+    const objects = branches(input, input).filter(
+      (branch) => branch.type === "object" || Object.hasOwn(branch, "properties"),
+    );
+    if (objects.length !== 1) {
+      issues.push("a entrada precisa ser um objeto com `id`, do tipo texto, como único campo obrigatório");
+    } else {
+      const [object] = objects;
+      const required = Array.isArray(object.required) ? object.required : [];
+      const id = object.properties?.id;
+      if (id === undefined || !required.includes("id")) {
+        issues.push("a entrada precisa ter `id` obrigatório");
+      } else if (!isText(id, input)) {
+        issues.push("o `id` da entrada precisa ser do tipo texto");
+      }
+      const others = required.filter((key) => key !== "id");
+      if (others.length > 0) {
+        issues.push(
+          `a entrada só pode exigir \`id\`, mas também exige ${others.map((key) => `\`${key}\``).join(", ")}; dê um valor padrão a esses campos ou torne-os opcionais`,
+        );
+      }
+    }
+  }
+  const reserved = [assistant.title, ...(Array.isArray(assistant.context) ? assistant.context : [])].filter(
+    (path) => reservedSegments(path).length > 0,
+  );
+  if (reserved.length > 0) {
+    issues.push(
+      `${reserved.map((path) => `\`${path}\``).join(", ")} usa __proto__, constructor ou prototype, que não são campos da saída`,
+    );
+    return issues;
+  }
+  if (unserializable(output)) {
+    issues.push("o schema de saída não pôde ser convertido em JSON Schema para conferir `title` e `context`");
+    return issues;
+  }
+  const missing = (path) => typeof path !== "string" || !schemaHasPath(output, path.split("."));
+  if (missing(assistant.title)) {
+    issues.push(`\`${assistant.title}\`, de \`title\`, não existe na saída`);
+  } else if (!schemaTitleIsText(output, assistant.title.split("."))) {
+    issues.push(
+      `\`${assistant.title}\`, de \`title\`, precisa ser texto ou número, fora de lista, para nomear o recurso`,
+    );
+  }
+  const absent = (Array.isArray(assistant.context) ? assistant.context : []).filter(missing);
+  if (absent.length > 0) {
+    const list = absent.map((path) => `\`${path}\``).join(", ");
+    issues.push(`${list}, de \`context\`, ${absent.length === 1 ? "não existe" : "não existem"} na saída`);
+  }
+  return issues;
+}
+
+/** O `ai` da action normalizado para o manifest. */
+export function serializeAiConfig(ai) {
+  const config = ai === true ? { enabled: true } : ai !== null && typeof ai === "object" ? ai : null;
+  return {
+    enabled: config !== null && config.enabled !== false,
+    description: typeof config?.description === "string" && config.description.length > 0 ? config.description : null,
+    destructive: config?.destructive === true,
+    requiresConfirmation: config?.requiresConfirmation === true,
+  };
+}

package/bin/lib/check.mjs

@@ -24,6 +24,12 @@
  *                            identificador exportado; um `entities` ou `purges` que o check não
  *                            consegue ler (spread, variável) suspende a regra de ausência
  *                            correspondente, sem falso positivo.
+ *   assistant-declaration  — o assistente do recurso (ADR 0053): só em action `view`, com `ai`
+ *                            habilitado, `personalData` declarado, `resource` em camelCase, `skill`
+ *                            em minúsculas com hífen, `label`, `title` e `context` presentes e
+ *                            `maxContextChars` literal de 1.000 a 16.000. O
+ *                            mesmo `resource` literal em duas actions, entre arquivos, reprova. Um
+ *                            `assistant` ou `ai` que não é literal suspende o que depende dele.
  *
  * A checagem cross-file de registro no runtime (graph) fica pra v2 (introspecção/MCP).
  * Saída: findings + exit ≠ 0 se houver erro. Zero actions num diretório NÃO-marcado
@@ -73,6 +79,7 @@ const FIELD_GROUP = {
   rateLimit: 5,
   idempotency: 5,
   ai: 6,
+  assistant: 6,
   automatable: 6,
   internal: 6,
 };
@@ -82,6 +89,17 @@ const FIELD_GROUP = {
 const SEG = "[a-z][a-z0-9]*(-[a-z0-9]+)*";
 const ACTION_NAME_RE = new RegExp(`^${SEG}(\\.${SEG})+$`);
 const KINDS = new Set(["simple", "form", "list", "view"]);
+// O assistente do recurso (ADR 0053): o mesmo formato que o registro do runtime confere.
+const ASSISTANT_RESOURCE_RE = /^[a-z][a-zA-Z0-9]*$/;
+const ASSISTANT_SKILL_RE = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+const ASSISTANT_CONTEXT_MIN = 1000;
+const ASSISTANT_RESERVED_SEGMENTS = new Set(["__proto__", "constructor", "prototype"]);
+const ASSISTANT_CONTEXT_MAX = 16000;
+const ASSISTANT_REQUIRED = {
+  label: "`label`, o nome do assistente para pessoas",
+  title: "`title`, o caminho do campo que nomeia o recurso",
+  context: "`context`, os caminhos dos campos que vão ao modelo",
+};
 // O runtime e o manifest só aplicam estes campos em `simple` e `form`; o tipo do binding os aceita
 // em qualquer kind, então a declaração num list/view compila e não tem efeito.
 const EXECUTION_ONLY_FIELDS = ["emits", "background"];
@@ -977,6 +995,73 @@ export function parseActions(fileName, sourceText) {
       .filter(Boolean);
   }
 
+  function prop(obj, key) {
+    return obj.properties.find(
+      (pr) =>
+        ts.isPropertyAssignment(pr) && pr.name && pr.name.getText(sf) === key,
+    );
+  }
+
+  /** `ai` literal → "enabled" | "disabled"; ausente → null; não literal → "unknown". */
+  function aiState(obj) {
+    const p = prop(obj, "ai");
+    if (!p) return obj.properties.some((pr) => pr.name?.getText(sf) === "ai") ? "unknown" : null;
+    const value = p.initializer;
+    if (value.kind === ts.SyntaxKind.TrueKeyword) return "enabled";
+    if (value.kind === ts.SyntaxKind.FalseKeyword) return "disabled";
+    if (ts.isObjectLiteralExpression(value)) {
+      const enabled = prop(value, "enabled");
+      if (!enabled) return "enabled";
+      if (enabled.initializer.kind === ts.SyntaxKind.FalseKeyword) return "disabled";
+      if (enabled.initializer.kind === ts.SyntaxKind.TrueKeyword) return "enabled";
+    }
+    return "unknown";
+  }
+
+  /** O `assistant` literal → { readable, resource, skill, keys }; ausente → null. */
+  function assistantDeclaration(obj) {
+    const p = prop(obj, "assistant");
+    if (!p) return null;
+    if (!ts.isObjectLiteralExpression(p.initializer))
+      return { readable: false, line: lineOf(p) };
+    const value = p.initializer;
+    const literal = (key) => {
+      const found = prop(value, key);
+      if (!found) return { present: objKeys(value).includes(key), text: null };
+      return {
+        present: true,
+        text: ts.isStringLiteralLike(found.initializer) ? found.initializer.text : null,
+      };
+    };
+    const limit = prop(value, "maxContextChars");
+    let maxContextChars = null;
+    if (limit) {
+      const node = limit.initializer;
+      if (ts.isNumericLiteral(node)) maxContextChars = Number(node.text.replace(/_/g, ""));
+      else if (
+        ts.isPrefixUnaryExpression(node) &&
+        node.operator === ts.SyntaxKind.MinusToken &&
+        ts.isNumericLiteral(node.operand)
+      )
+        maxContextChars = -Number(node.operand.text.replace(/_/g, ""));
+    }
+    const contextNode = prop(value, "context");
+    const contextPaths =
+      contextNode && ts.isArrayLiteralExpression(contextNode.initializer)
+        ? contextNode.initializer.elements.filter(ts.isStringLiteralLike).map((element) => element.text)
+        : [];
+    return {
+      readable: true,
+      line: lineOf(p),
+      resource: literal("resource"),
+      skill: literal("skill"),
+      title: literal("title"),
+      contextPaths,
+      maxContextChars,
+      keys: objKeys(value),
+    };
+  }
+
   function visit(node) {
     if (ts.isCallExpression(node) && ts.isIdentifier(node.expression)) {
       const callee = node.expression.text;
@@ -992,6 +1077,8 @@ export function parseActions(fileName, sourceText) {
           name: strProp(obj, "name"),
           kind: strProp(obj, "kind"),
           effect: strProp(obj, "effect"),
+          ai: aiState(obj),
+          assistant: assistantDeclaration(obj),
           keys: objKeys(obj),
           ident: constIdent(node),
           exported: isExported(node),
@@ -1023,6 +1110,61 @@ export function parseActions(fileName, sourceText) {
   return actions;
 }
 
+/**
+ * Regra `assistant-declaration` (ADR 0053) sobre um item: a forma do assistente do recurso. O
+ * `resource` repetido entre actions é conferido no `checkProject`.
+ */
+function assistantMessages(a) {
+  const assistant = a.assistant;
+  if (assistant === null || assistant === undefined) return [];
+  const out = [];
+  if (a.kind !== null && a.kind !== "view")
+    out.push(
+      `Só uma action view declara assistente, e esta é ${a.kind}. A leitura de um recurso identificado é o papel da view.`,
+    );
+  if (a.ai === null || a.ai === "disabled")
+    out.push(
+      "A action dona precisa estar publicada para a IA: declare `ai: true` ou `ai` sem `enabled: false`.",
+    );
+  if (!a.keys.includes("personalData"))
+    out.push(
+      "A action dona precisa declarar `personalData`, `true` ou `false`: a declaração decide como o host trata o dado que entrega ao modelo.",
+    );
+  if (!assistant.readable) return out;
+  const { resource, skill } = assistant;
+  if (!resource.present)
+    out.push("O assistente precisa declarar `resource`, o tipo de recurso de que a action é dona.");
+  else if (resource.text !== null && !ASSISTANT_RESOURCE_RE.test(resource.text))
+    out.push(`\`resource: "${resource.text}"\` precisa estar em camelCase, como \`customer\` ou \`aftersaleOpportunity\`.`);
+  if (!skill.present)
+    out.push("O assistente precisa declarar `skill`, a chave do procedimento que a IA segue.");
+  else if (skill.text !== null && !ASSISTANT_SKILL_RE.test(skill.text))
+    out.push(`\`skill: "${skill.text}"\` precisa estar em minúsculas com hífen, como \`review-customer\`.`);
+  const reserved = [assistant.title.text, ...assistant.contextPaths].filter(
+    (path) =>
+      typeof path === "string" &&
+      path.split(".").some((segment) => ASSISTANT_RESERVED_SEGMENTS.has(segment)),
+  );
+  if (reserved.length > 0)
+    out.push(
+      `${reserved.map((path) => `\`${path}\``).join(", ")} usa __proto__, constructor ou prototype, que não são campos da saída.`,
+    );
+  const limit = assistant.maxContextChars;
+  if (
+    limit !== null &&
+    (!Number.isInteger(limit) || limit < ASSISTANT_CONTEXT_MIN || limit > ASSISTANT_CONTEXT_MAX)
+  )
+    out.push(
+      `\`maxContextChars: ${limit}\` precisa ser um inteiro de 1.000 a 16.000; sem ele, o teto é de 4.000 caracteres.`,
+    );
+  const missing = Object.keys(ASSISTANT_REQUIRED).filter((key) => !assistant.keys.includes(key));
+  if (missing.length > 0)
+    out.push(
+      `O assistente precisa declarar ${missing.map((key) => ASSISTANT_REQUIRED[key]).join("; ")}.`,
+    );
+  return out;
+}
+
 /** Aplica as regras locais (por arquivo) a um item → findings. */
 export function lintAction(a) {
   const out = [];
@@ -1088,6 +1230,15 @@ export function lintAction(a) {
   const ignored = ignoredByKindMessage(a.kind, a.keys);
   if (ignored !== null) at("ignored-by-kind", ignored);
 
+  for (const message of assistantMessages(a))
+    out.push({
+      rule: "assistant-declaration",
+      level: "error",
+      action: label,
+      line: a.assistant.line,
+      message,
+    });
+
   if (
     a.form === "defineAction" &&
     a.keys.includes("requires") &&
@@ -1126,6 +1277,7 @@ export function checkProject(sources) {
   const entityNames = new Set();
   const actionNames = new Set();
   const retention = [];
+  const assistantResources = new Map(); // resource literal → [{ item, file }]
   // Natureza da action (ADR 0041): declarações ausentes são contadas, não reprovadas, na minor.
   let missingEffect = 0;
   let missingPersonalData = 0;
@@ -1159,6 +1311,12 @@ export function checkProject(sources) {
         if (item.name !== null) actionNames.add(item.name);
       }
       for (const f of lintAction(item)) findings.push({ ...f, file });
+      const resource = item.assistant?.resource?.text ?? null;
+      if (resource !== null) {
+        const owners = assistantResources.get(resource) ?? [];
+        owners.push({ item, file });
+        assistantResources.set(resource, owners);
+      }
       if (item.form !== "bindAction") {
         const writesByGet = item.kind === "list" || item.kind === "view";
         if (!writesByGet && !item.keys.includes("effect")) missingEffect += 1;
@@ -1265,6 +1423,21 @@ export function checkProject(sources) {
     }
   }
 
+  for (const [resource, owners] of assistantResources) {
+    if (owners.length < 2) continue;
+    const names = owners.map(({ item }) => item.name ?? item.ident ?? "(sem name)");
+    for (const { item, file } of owners) {
+      findings.push({
+        rule: "assistant-declaration",
+        level: "error",
+        action: item.name ?? item.ident ?? "(sem name)",
+        line: item.assistant.line,
+        file,
+        message: `O recurso "${resource}" tem mais de uma action dona (${names.join(", ")}). Cada tipo de recurso tem uma única action dona.`,
+      });
+    }
+  }
+
   findings.push(...checkRetention(retention));
 
   return {

package/bin/lib/copy.mjs

@@ -1540,6 +1540,8 @@ export function extractCopyFromSource(file, sourceText) {
       addProperty(example, 'description', 'description', prefix)
     })
     nestedObject(object, 'errors', (error, prefix) => addProperty(error, 'description', 'error', prefix))
+    // O nome do assistente do recurso (ADR 0053), que a interface mostra como título do chat.
+    nestedObject(object, 'assistant', (assistant, prefix) => addProperty(assistant, 'label', 'title', prefix))
   }
 
   function extractPresentation(object) {