@softize/opus 15.1.0 → 15.2.1

package/CHANGELOG.md

@@ -7,6 +7,33 @@ 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.
 
+## 15.2.1 — 2026-09-11
+
+`opus copy` agora poda diretórios cobertos por um glob recursivo de `copy.exclude`, em vez de
+percorrer toda a árvore para só então descartar seus arquivos. Isso evita custo desnecessário e
+travamentos aparentes em repositórios que mantêm worktrees ou artefatos volumosos dentro da raiz.
+
+**Migração:** nenhuma. Projetos com diretórios locais volumosos devem declará-los em
+`copy.exclude` com um glob recursivo, como `.worktrees/**`.
+
+## 15.2.0 — 2026-09-11
+
+Produtos de Dados passam a ser declarações de primeira classe com `defineDataProduct` e registro
+em `defineDomain({ dataProducts })`. Identidade, versão, responsável, grão, classificação,
+natureza, Fontes, entities, acesso descritivo, interfaces e ciclo de vida seguem para o manifest.
+O domínio e `opus check` detectam IDs duplicados e referências inexistentes. Actions oferecidas à
+IA carregam os produtos que expõem; MCP projeta a relação em
+`_meta['com.softize.opus/data-products']`. Autorização e recorte continuam obrigatoriamente nas
+Actions — metadata de produto não abre acesso.
+
+O `<Chat>` aceita `id` e `createdAt` nos itens, gera esses campos para mensagens que administra e
+oferece `renderMessageActions`. O slot aparece em hover ou foco e permite que o app carregue ações
+e detalhes contextuais sem acoplar o componente a uma implementação de observabilidade.
+
+**Migração:** nenhuma para declarações existentes. Para catalogar um produto, declare-o, registre-o
+no domínio e mantenha todas as Actions citadas em `interfaces` protegidas. Históricos antigos sem
+`id` ou `createdAt` continuam renderizando.
+
 ## 15.1.0 — 2026-09-10
 
 `PageShell` passa a coordenar o chrome persistente quando shell e rota conhecem partes diferentes da

package/README.md

@@ -15,7 +15,7 @@ Protocolo de actions de ponta a ponta para TypeScript. Declare uma vez — input
 - **Contrato, não feature.** Tudo que entra no core padroniza forma; tudo que faz trabalho usa lib externa.
 - **Fail-closed por default.** Action sem `authorize` é negada. Audit default-on.
 - **Adapters plugáveis.** Cada categoria é uma superfície (subpath) com interface fechada e drivers trocáveis.
-- **Declaração é a fonte; doc é projeção.** As declarações (`defineContract`, `bindAction`, `defineEntity`) são a fonte dos contratos; manifest, OpenAPI e a doc gerada são projeções. `docs/protocol.md` descreve o protocolo em 16 seções (15 + glossário).
+- **Declaração é a fonte; doc é projeção.** As declarações (`defineContract`, `bindAction`, `defineEntity`, `defineDataProduct`) são a fonte dos contratos; manifest, OpenAPI e a doc gerada são projeções. `docs/protocol.md` descreve o protocolo em 16 seções (15 + glossário).
 
 ## Superfícies
 
@@ -23,7 +23,7 @@ Um pacote (`@softize/opus`), uma versão. Cada categoria abaixo é um **subpath
 
 | Superfície | Drivers | Propósito |
 |---|---|---|
-| `@softize/opus` (core) | — | Protocolo, `defineContract`, `bindAction`, `defineAction`, `defineEntity`, runtime |
+| `@softize/opus` (core) | — | Protocolo, Actions, entities, Produtos de Dados e runtime |
 | `@softize/opus/schema` | `/zod`, `/openapi` | Tipos lógicos (`t.*`) e gerador de OpenAPI |
 | `@softize/opus/server` | `/fastify`, `/node` | Transporte HTTP e montagem de endpoints |
 | `@softize/opus/client` | `/fetch` | Adapter de cliente para invocar actions |
@@ -95,7 +95,7 @@ registry/    # scaffolds + skills Opus — geração e conhecimento do SDK, não
 bin/         # CLI (opus create/setup/gen/copy/check/db/seed/pre-push/introspect/mcp) + libs
 docs/
   protocol.md   # contrato completo (16 seções)
-  data-layer.md · seeds.md · releasing.md · code-style.md
+  data-layer.md · data-products.md · seeds.md · releasing.md · code-style.md
 ```
 
 ## Seeds de projeto

package/bin/lib/check.mjs

@@ -323,6 +323,54 @@ const UI_LEGACY_VARIANTS = new Map([
 
 /** Os três nomes que denotam action/contrato — o arquivo sem nenhum deles é pulado. */
 export const ACTION_MARKERS = ["defineAction", "defineContract", "bindAction"];
+export const DATA_PRODUCT_MARKERS = ["defineDataProduct", "defineEntity"];
+
+/** Extrai Produtos de Dados e entities literais para validar a linhagem sem executar o app. */
+export function parseDataProducts(fileName, sourceText) {
+  const sf = ts.createSourceFile(fileName, sourceText, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+  const products = [];
+  const entities = [];
+  const lineOf = (node) => sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1;
+  const prop = (obj, key) => obj.properties.find((item) =>
+    ts.isPropertyAssignment(item) && item.name?.getText(sf) === key)?.initializer;
+  const stringProp = (obj, key) => {
+    const value = prop(obj, key);
+    return value && ts.isStringLiteral(value) ? value.text : null;
+  };
+  const stringList = (obj, key) => {
+    const value = prop(obj, key);
+    if (!value || !ts.isArrayLiteralExpression(value)) return null;
+    if (!value.elements.every(ts.isStringLiteral)) return null;
+    return value.elements.map((item) => item.text);
+  };
+  const isExported = (call) => {
+    const declaration = call.parent;
+    const statement = ts.isVariableDeclaration(declaration) ? declaration.parent?.parent : undefined;
+    return statement !== undefined && ts.isVariableStatement(statement) && (statement.modifiers ?? []).some((item) => item.kind === ts.SyntaxKind.ExportKeyword);
+  };
+  const visit = (node) => {
+    if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && node.arguments[0] && ts.isObjectLiteralExpression(node.arguments[0])) {
+      const obj = node.arguments[0];
+      if (node.expression.text === "defineDataProduct") {
+        const versionNode = prop(obj, "version");
+        products.push({
+          id: stringProp(obj, "id"),
+          version: versionNode && ts.isNumericLiteral(versionNode) ? Number(versionNode.text) : null,
+          interfaces: stringList(obj, "interfaces"),
+          entities: stringList(obj, "entities"),
+          exported: isExported(node),
+          line: lineOf(node),
+        });
+      } else if (node.expression.text === "defineEntity") {
+        const name = stringProp(obj, "name");
+        if (name !== null) entities.push(name);
+      }
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sf);
+  return { products, entities };
+}
 
 /**
  * Extrai `defineAction`/`defineContract`/`bindAction` de um source. Puro/sintático —
@@ -516,14 +564,21 @@ export function checkProject(sources) {
   const findings = [];
   const contractsByIdent = new Map(); // ident → item | 'ambiguous'
   const binds = []; // { item, file }
+  const productDeclarations = [];
+  const entityNames = new Set();
+  const actionNames = new Set();
 
   for (const { file, text } of sources) {
+    const declarations = parseDataProducts(file, text);
+    for (const entity of declarations.entities) entityNames.add(entity);
+    for (const product of declarations.products) productDeclarations.push({ product, file });
     for (const item of parseActions(file, text)) {
       if (item.form === "bindAction") {
         actions += 1;
         binds.push({ item, file });
       } else if (item.form === "defineContract") {
         contracts += 1;
+        if (item.name !== null) actionNames.add(item.name);
         if (item.ident !== null) {
           contractsByIdent.set(
             item.ident,
@@ -532,11 +587,45 @@ export function checkProject(sources) {
         }
       } else {
         actions += 1;
+        if (item.name !== null) actionNames.add(item.name);
       }
       for (const f of lintAction(item)) findings.push({ ...f, file });
     }
   }
 
+  const productIds = new Set();
+  for (const { product, file } of productDeclarations) {
+    const finding = (rule, message) => findings.push({
+      rule, level: "error", action: product.id ?? "(Produto de Dados sem id)",
+      line: product.line, file, message,
+    });
+    if (!product.exported) finding("data-product-export", "defineDataProduct precisa ser `export const` para compor o domínio e o catálogo.");
+    if (product.id === null || !ACTION_NAME_RE.test(product.id)) {
+      finding("data-product-id", "Produto de Dados precisa de `id` namespaced literal, como `sales.leads`.");
+    } else if (productIds.has(product.id)) {
+      finding("data-product-duplicate", `Produto de Dados "${product.id}" está declarado mais de uma vez.`);
+    } else {
+      productIds.add(product.id);
+    }
+    if (product.version === null || !Number.isInteger(product.version) || product.version < 1) {
+      finding("data-product-version", "Produto de Dados precisa de `version` literal inteira e positiva.");
+    }
+    if (product.interfaces === null || product.interfaces.length === 0) {
+      finding("data-product-interfaces", "Produto de Dados precisa declarar ao menos uma Action literal em `interfaces`.");
+    } else {
+      for (const action of product.interfaces) {
+        if (!actionNames.has(action)) finding("data-product-interface", `A interface "${action}" não corresponde a uma Action ou contrato declarado no projeto.`);
+      }
+    }
+    if (product.entities === null) {
+      finding("data-product-entities", "Produto de Dados precisa declarar `entities` como lista literal.");
+    } else {
+      for (const entity of product.entities) {
+        if (!entityNames.has(entity)) finding("data-product-entity", `A Entity "${entity}" não foi declarada no projeto.`);
+      }
+    }
+  }
+
   for (const { item, file } of binds) {
     const contract = contractsByIdent.get(item.contractRef);
     if (contract === undefined || contract === "ambiguous") continue;
@@ -555,7 +644,7 @@ export function checkProject(sources) {
     }
   }
 
-  return { actions, contracts, findings };
+  return { actions, contracts, dataProducts: productDeclarations.length, findings };
 }
 
 /** Migrações de UI que falhariam apenas visualmente. Linhas que são só comentário não
@@ -1408,7 +1497,7 @@ export async function scanDir(rootDir) {
   const sources = [];
   for (const file of files) {
     const text = readProjectFile(rootDir, path.relative(rootDir, file)).content;
-    if (!ACTION_MARKERS.some((m) => text.includes(m))) continue;
+    if (![...ACTION_MARKERS, ...DATA_PRODUCT_MARKERS].some((m) => text.includes(m))) continue;
     sources.push({ file: path.relative(rootDir, file), text });
   }
   const checked = checkProject(sources);
@@ -1424,6 +1513,7 @@ export async function scanDir(rootDir) {
     files: files.length,
     actions: checked.actions,
     contracts: checked.contracts,
+    dataProducts: checked.dataProducts,
     findings: [...checked.findings, ...uiFindings],
     hasMarker,
   };

package/bin/lib/copy.mjs

@@ -2146,6 +2146,14 @@ function globRegex(pattern) {
 function sourceFiles(root, excluded = []) {
   const output = []
   const diagnostics = []
+  const excludedPatterns = excluded.map((pattern) => ({
+    regex: globRegex(pattern),
+    subtree: pattern.endsWith('/**') ? globRegex(pattern.slice(0, -3)) : null,
+  }))
+  const isExcluded = (source) => excludedPatterns.some(({ regex }) => regex.test(source))
+  const isExcludedDirectory = (source) => excludedPatterns.some(({ regex, subtree }) =>
+    regex.test(source) || subtree?.test(source),
+  )
   const walk = (directory = '.') => {
     let listing
     try {
@@ -2162,8 +2170,9 @@ function sourceFiles(root, excluded = []) {
       const target = path.join(directory, item.name)
       const source = portable(target === '.' ? item.name : target)
       if (IGNORED_DIRECTORIES.has(item.name)) continue
+      if (item.isDirectory() && isExcludedDirectory(source)) continue
       if (item.isSymbolicLink()) {
-        if (!excluded.some((pattern) => globRegex(pattern).test(source))) {
+        if (!isExcluded(source) && !isExcludedDirectory(source)) {
           diagnostics.push({
             source,
             line: 1,
@@ -2189,7 +2198,7 @@ function sourceFiles(root, excluded = []) {
         item.isFile() &&
         SOURCE_EXTENSIONS.has(path.extname(item.name)) &&
         !IGNORED_FILE.test(item.name) &&
-        !excluded.some((pattern) => globRegex(pattern).test(source))
+        !isExcluded(source)
       ) {
         try {
           const inspected = safeProjectPath(root, target, { mustExist: true })

package/bin/lib/gen-manifest.mjs

@@ -27,6 +27,7 @@ function shapeDomain(d) {
     repository: d.hasRepository,
     service: d.hasService,
     entities: d.entities ?? [],
+    dataProducts: d.dataProducts ?? [],
     actions: d.actions.map(shapeAction),
     reactions: d.reactions,
     schedules: d.schedules,

package/bin/lib/gen-runner.mjs

@@ -178,6 +178,7 @@ function serializeDomain(domain, ctx) {
     hasRepository: domain.repository !== undefined,
     hasService: domain.service !== undefined,
     entities: entityList,
+    dataProducts: serializeDataProducts(domain.dataProducts),
     dicts: serializeDicts(domain.dicts),
     actions: Array.from(iterateActions(domain.actions), (a) =>
       serializeAction(a, ctx),
@@ -194,6 +195,42 @@ function serializeDomain(domain, ctx) {
   }
 }
 
+function serializeDataProducts(source) {
+  if (source === undefined || source === null) return []
+  const products = Array.isArray(source)
+    ? source
+    : typeof source === 'object'
+      ? Object.values(source)
+      : []
+  return products.map((product) => ({
+    id: product.id,
+    version: product.version,
+    label: product.label,
+    description: product.description,
+    owner: product.owner,
+    grain: product.grain,
+    classification: product.classification,
+    nature: product.nature,
+    sources: Array.isArray(product.sources)
+      ? product.sources.map((source) => ({
+          id: source.id,
+          label: source.label,
+          description: nullable(source.description),
+        }))
+      : [],
+    entities: Array.isArray(product.entities) ? product.entities : [],
+    access: {
+      contexts: Array.isArray(product.access?.contexts) ? product.access.contexts : [],
+      organizationalScopes: Array.isArray(product.access?.organizationalScopes)
+        ? product.access.organizationalScopes
+        : [],
+    },
+    interfaces: Array.isArray(product.interfaces) ? product.interfaces : [],
+    status: product.status ?? 'active',
+    replacedBy: nullable(product.replacedBy),
+  }))
+}
+
 /** Serializa as entidades (`defineEntity`) com campos + docs — a fonte que vai pro
  *  manifest/lente. Ignora valores que não parecem EntityConfig (name+fields). */
 function serializeEntities(src) {

package/bin/lib/introspect.mjs

@@ -28,10 +28,10 @@ function asStringArray(init) {
   return []
 }
 
-/** Extrai actions/reactions/schedules de um source. Puro/sintático — testável. */
+/** Extrai actions/reactions/schedules/Produtos de Dados de um source. Puro/sintático — testável. */
 export function parseStructure(fileName, sourceText) {
   const sf = ts.createSourceFile(fileName, sourceText, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS)
-  const out = { actions: [], reactions: [], schedules: [] }
+  const out = { actions: [], reactions: [], schedules: [], dataProducts: [] }
   const line = (n) => sf.getLineAndCharacterOfPosition(n.getStart(sf)).line + 1
 
   function visit(node) {
@@ -64,6 +64,17 @@ export function parseStructure(fileName, sourceText) {
           every: asString(prop(obj, 'every', sf)),
           line: line(node),
         })
+      } else if (fn === 'defineDataProduct') {
+        out.dataProducts.push({
+          id: asString(prop(obj, 'id', sf)),
+          version: (() => {
+            const value = prop(obj, 'version', sf)
+            return value && ts.isNumericLiteral(value) ? Number(value.text) : null
+          })(),
+          entities: asStringArray(prop(obj, 'entities', sf)),
+          interfaces: asStringArray(prop(obj, 'interfaces', sf)),
+          line: line(node),
+        })
       }
     }
     ts.forEachChild(node, visit)
@@ -94,15 +105,16 @@ export function deriveWiring(model) {
 export async function introspect(rootDir) {
   rootDir = canonicalProjectDirectory(rootDir)
   const files = await walkTsFiles(rootDir)
-  const model = { actions: [], reactions: [], schedules: [] }
+  const model = { actions: [], reactions: [], schedules: [], dataProducts: [] }
   for (const file of files) {
     const text = readProjectFile(rootDir, path.relative(rootDir, file)).content
-    if (!/define(Action|Reaction|Schedule)/.test(text)) continue
+    if (!/define(Action|Reaction|Schedule|DataProduct)/.test(text)) continue
     const s = parseStructure(file, text)
     const rel = path.relative(rootDir, file)
     for (const a of s.actions) model.actions.push({ ...a, file: rel })
     for (const r of s.reactions) model.reactions.push({ ...r, file: rel })
     for (const sc of s.schedules) model.schedules.push({ ...sc, file: rel })
+    for (const product of s.dataProducts) model.dataProducts.push({ ...product, file: rel })
   }
   return { ...model, wiring: deriveWiring(model) }
 }

package/docs/adr/0012-data-products-are-first-class-declarations.md

@@ -0,0 +1,72 @@
+# ADR 0012 — Produtos de Dados são declarações de primeira classe
+
+- Status: aceita
+- Data: 2026-09-11
+
+## Contexto e forças
+
+Entities descrevem estrutura persistida e Actions descrevem interfaces autorizadas. Nenhuma das
+duas declara, porém, qual conjunto governado existe para responder uma pergunta de negócio. Sem
+esse artefato, relatórios, agentes e catálogos reconstroem a relação entre Fonte, Entity e Action
+por nomes ou tabelas paralelas. A mesma análise pode então receber uma definição diferente a cada
+novo consumidor.
+
+Uma view de banco não resolve o problema: ela pode ser uma implementação eficiente, mas não
+carrega por si só identidade pública, responsável, grão, classificação, linhagem, interfaces ou
+ciclo de vida. Também não queremos que metadata descritiva contorne o pipeline de autorização da
+Action.
+
+## Decisão
+
+O core expõe `defineDataProduct`. O produto tem identidade namespaced e estável, versão inteira,
+nome e descrição humanas, responsável, grão, classificação, natureza, Fontes, entities, acesso
+descritivo e Actions de interface. Produtos ativos podem ser descontinuados com `status:
+'deprecated'` e `replacedBy`.
+
+`defineDomain({ dataProducts })` registra os produtos. O domínio e `opus check` recusam IDs
+duplicados e relações literais que apontam para Action ou Entity inexistente. A declaração não
+executa consulta, não contém driver e não substitui uma Action.
+
+A autorização continua sendo responsabilidade da Action. `access.contexts` e
+`access.organizationalScopes` documentam o alcance esperado para catálogo, Lens e revisão, mas o
+runtime não os converte em autorização implícita. Essa separação impede que uma descrição
+incompleta abra dados.
+
+O manifest projeta a declaração integral. Tools de IA recebem a lista de produtos que expõem em
+metadata, e o servidor MCP publica essa lista em `_meta['com.softize.opus/data-products']`. A
+camada que compõe MCPs pode persistir a linhagem das chamadas bem-sucedidas sem conhecer tabelas
+ou inferir produtos pelo nome da tool.
+
+## Alternativas consideradas
+
+### Tratar Entity como Produto de Dados
+
+Rejeitada. Uma Entity descreve estrutura e invariantes; um produto pode combinar várias entities,
+ter outro grão e oferecer mais de uma interface.
+
+### Usar view ou tabela consolidada como identidade
+
+Rejeitada como contrato. Views continuam válidas como implementação de performance, mas trocar a
+materialização não deve trocar a identidade consumida por relatório, agente ou interface.
+
+### Manter um catálogo manual fora do domínio
+
+Rejeitada. O catálogo voltaria a divergir das Actions e entities que realmente existem.
+
+## Consequências
+
+Um produto novo exige decisão explícita sobre semântica, acesso e linhagem antes de ser publicado.
+O custo adicional é intencional. Mudança de forma observável incrementa `version`; substituição
+preserva o ID antigo como descontinuado durante a migração dos consumidores.
+
+Relatórios e agentes passam a depender da identidade do produto, enquanto cada Action permanece
+a fronteira executável e autorizada. O Opus Lens pode apresentar a cadeia `Fonte/Entity → Produto
+de Dados → Action` a partir do manifest.
+
+## Verificação
+
+- testes de construção e registro cobrem formato, duplicidade, ciclo de vida e referências;
+- `opus check` cobre declarações literais, exportação e drift de Action/Entity;
+- o manifest preserva todos os campos;
+- runtime de IA e MCP projetam a identidade do produto por interface;
+- Opus Lens lê a declaração e deriva a linhagem sem heurística.

package/docs/data-products.md

@@ -0,0 +1,66 @@
+---
+title: Produtos de Dados
+order: 7
+---
+
+# Produtos de Dados
+
+Um Produto de Dados dá identidade governada ao conjunto que uma ou mais Actions disponibilizam.
+Ele não é uma query, tabela ou view: essas são implementações possíveis. A fronteira de execução,
+recorte e autorização continua sendo cada Action.
+
+```ts
+import { defineDataProduct, defineDomain } from '@softize/opus'
+
+export const salesLeads = defineDataProduct({
+  id: 'sales.leads',
+  version: 1,
+  label: 'Leads comerciais',
+  description: 'Leads e seus resultados comerciais.',
+  owner: 'Vendas',
+  grain: 'Um lead.',
+  classification: 'internal',
+  nature: 'real',
+  sources: [{ id: 'followize', label: 'Followize' }],
+  entities: ['Lead'],
+  access: {
+    contexts: ['sales'],
+    organizationalScopes: ['unit', 'team'],
+  },
+  interfaces: ['sale.list', 'sales.performance'],
+})
+
+export const salesDomain = defineDomain({
+  name: 'sales',
+  entities: { Lead },
+  actions: { saleList, salesPerformance },
+  dataProducts: { salesLeads },
+})
+```
+
+`interfaces` e `entities` usam os nomes declarados, não nomes de arquivo ou tabela. O registro do
+domínio e `opus check` detectam relações inexistentes. `sources` identifica sistemas ou conjuntos
+upstream; uma Fonte não precisa ser uma Entity Opus.
+
+## Acesso e segurança
+
+`access` é documentação verificável do alcance esperado. Ele ajuda catálogo e revisão a perceber
+que uma interface deveria respeitar, por exemplo, unidade e equipe. Não é RLS nem autorização
+automática. Toda interface precisa aplicar seus próprios `requires`, `authorize` e recortes no
+handler/repositório, inclusive quando for chamada por IA ou MCP.
+
+## Projeções
+
+`opus gen` publica os produtos no `.opus/manifest.json`. Actions expostas como tools carregam os
+IDs em `metadata.dataProducts`; no MCP, a chave é
+`_meta['com.softize.opus/data-products']`. Consumidores devem registrar apenas produtos associados
+a chamadas concluídas com sucesso.
+
+O Opus Lens usa o manifest para mostrar a linhagem declarada entre Fontes, entities, produtos e
+Actions. Nenhuma dessas projeções é fonte autoritativa: corrija a declaração e gere novamente.
+
+## Ciclo de vida
+
+Incremente `version` quando a forma observável do produto mudar. Para substituí-lo, mantenha a
+declaração anterior com `status: 'deprecated'` e `replacedBy` apontando para o novo ID durante a
+migração. Produto ativo não declara `replacedBy`.

package/docs/protocol.md

@@ -2084,6 +2084,18 @@ export const crm = defineDomain({
 
 ---
 
+### 15.1 Produtos de Dados
+
+`defineDataProduct` declara um conjunto governado consumível por pessoas, relatórios ou agentes.
+Ele liga Fontes e entities às Actions que formam sua interface, sem conter query, driver ou regra
+de autorização. O formato completo, o ciclo de vida e as projeções estão em
+[Produtos de Dados](data-products.md); a decisão arquitetural está na
+[ADR 0012](adr/0012-data-products-are-first-class-declarations.md).
+
+A declaração de `access` é descritiva. O pipeline da Action permanece a única fronteira
+executável: `requires`, `authorize`, carregamentos e recortes continuam sendo aplicados em toda
+chamada, inclusive por IA e MCP.
+
 ## 16. Glossário
 
 - **Action** — unidade declarativa que flui pelo pipeline opus. Ver §2.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softize/opus",
-  "version": "15.1.0",
+  "version": "15.2.1",
   "description": "End-to-end action protocol for TypeScript. Single package with subpath exports (core + adapters).",
   "license": "MIT",
   "type": "module",
@@ -212,6 +212,17 @@
   "bin": {
     "opus": "bin/cli.mjs"
   },
+  "scripts": {
+    "postinstall": "node ./bin/lib/postinstall.mjs",
+    "copy:check": "node ./bin/cli.mjs copy --check",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:cov": "vitest run --coverage",
+    "registry:up": "npx -y verdaccio --config ~/.config/verdaccio/config.yaml",
+    "release": "bash ./scripts/release.sh",
+    "release:local": "bash ./scripts/release.sh --local"
+  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@radix-ui/react-checkbox": "^1.1.3",
@@ -357,21 +368,11 @@
     "vitest": "^2.1.0",
     "zod": "^3.24.0"
   },
+  "packageManager": "pnpm@9.0.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/softize-dev/opus.git",
     "directory": "packages/opus"
   },
-  "homepage": "https://opus.softize.com.br",
-  "scripts": {
-    "postinstall": "node ./bin/lib/postinstall.mjs",
-    "copy:check": "node ./bin/cli.mjs copy --check",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:cov": "vitest run --coverage",
-    "registry:up": "npx -y verdaccio --config ~/.config/verdaccio/config.yaml",
-    "release": "bash ./scripts/release.sh",
-    "release:local": "bash ./scripts/release.sh --local"
-  }
-}
+  "homepage": "https://opus.softize.com.br"
+}

package/src/core/data-product.ts

@@ -0,0 +1,121 @@
+/**
+ * Um Produto de Dados é um dataset governado e estável que uma ou mais Actions expõem.
+ * A declaração descreve o produto; autorização e recorte continuam pertencendo às Actions.
+ */
+
+export type DataProductStatus = 'active' | 'deprecated'
+
+export interface DataProductSource {
+  /** Identificador técnico estável da Fonte. */
+  id: string
+  /** Nome humano projetado por catálogos e lentes. */
+  label: string
+  description?: string
+}
+
+export interface DataProductAccess {
+  /** Contextos de dados normalmente exigidos pelas interfaces do produto. Descritivo. */
+  contexts: readonly string[]
+  /** Eixos organizacionais que as Actions precisam considerar, como unit e team. Descritivo. */
+  organizationalScopes: readonly string[]
+}
+
+export interface DataProductConfig {
+  /** Identidade estável e namespaced, como `sales.leads`. */
+  id: string
+  /** Versão semântica inteira da forma observável do produto. */
+  version: number
+  label: string
+  description: string
+  /** Responsável técnico ou de negócio pelo produto. */
+  owner: string
+  /** O que uma linha ou observação representa. */
+  grain: string
+  /** Classificação definida pelo produto, como `internal` ou `personal`. */
+  classification: string
+  /** Natureza definida pelo produto, como `real`, `demo` ou `synthetic`. */
+  nature: string
+  sources: readonly DataProductSource[]
+  /** Entidades Opus que materializam ou estruturam o produto. */
+  entities: readonly string[]
+  access: DataProductAccess
+  /** Nomes de Actions que disponibilizam este produto. */
+  interfaces: readonly string[]
+  status?: DataProductStatus
+  /** Produto sucessor quando este estiver descontinuado. */
+  replacedBy?: string
+}
+
+const ID_RE = /^[a-z][a-z0-9_-]*(?:\.[a-z][a-z0-9_-]*)+$/
+
+function nonEmpty(value: unknown, field: string): void {
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw new TypeError(`DataProduct "${field}" deve ser string não-vazia`)
+  }
+}
+
+/** Declara e valida um Produto de Dados sem introduzir dependência de banco ou runtime. */
+export function defineDataProduct<const T extends DataProductConfig>(config: T): T {
+  if (!ID_RE.test(config.id)) {
+    throw new TypeError(`DataProduct id "${config.id}" deve ser namespaced e casar com ${ID_RE.source}`)
+  }
+  if (!Number.isInteger(config.version) || config.version < 1) {
+    throw new TypeError('DataProduct "version" deve ser inteiro positivo')
+  }
+  for (const field of ['label', 'description', 'owner', 'grain', 'classification', 'nature'] as const) {
+    nonEmpty(config[field], field)
+  }
+  if (!Array.isArray(config.sources) || config.sources.length === 0) {
+    throw new TypeError('DataProduct "sources" deve declarar ao menos uma Fonte')
+  }
+  const sourceIds = new Set<string>()
+  for (const source of config.sources) {
+    nonEmpty(source.id, 'sources[].id')
+    nonEmpty(source.label, 'sources[].label')
+    if (source.description !== undefined) nonEmpty(source.description, 'sources[].description')
+    if (sourceIds.has(source.id)) throw new TypeError(`DataProduct Fonte "${source.id}" duplicada`)
+    sourceIds.add(source.id)
+  }
+  if (!Array.isArray(config.entities)) {
+    throw new TypeError('DataProduct "entities" deve ser uma lista')
+  }
+  if (new Set(config.entities).size !== config.entities.length) {
+    throw new TypeError(`DataProduct "${config.id}" possui Entity duplicada`)
+  }
+  for (const entity of config.entities) nonEmpty(entity, 'entities[]')
+  if (!Array.isArray(config.interfaces) || config.interfaces.length === 0) {
+    throw new TypeError('DataProduct "interfaces" deve declarar ao menos uma Action')
+  }
+  if (new Set(config.interfaces).size !== config.interfaces.length) {
+    throw new TypeError(`DataProduct "${config.id}" possui interface duplicada`)
+  }
+  for (const action of config.interfaces) nonEmpty(action, 'interfaces[]')
+  if (!Array.isArray(config.access?.contexts) || !Array.isArray(config.access?.organizationalScopes)) {
+    throw new TypeError('DataProduct "access" deve declarar contexts e organizationalScopes')
+  }
+  for (const context of config.access.contexts) nonEmpty(context, 'access.contexts[]')
+  for (const scope of config.access.organizationalScopes) nonEmpty(scope, 'access.organizationalScopes[]')
+  if (config.status !== undefined && config.status !== 'active' && config.status !== 'deprecated') {
+    throw new TypeError('DataProduct "status" deve ser "active" ou "deprecated"')
+  }
+  if (config.status === 'deprecated') {
+    nonEmpty(config.replacedBy, 'replacedBy')
+    if (!ID_RE.test(config.replacedBy!)) {
+      throw new TypeError(`DataProduct replacedBy "${config.replacedBy}" deve ser namespaced e casar com ${ID_RE.source}`)
+    }
+    if (config.replacedBy === config.id) throw new TypeError('DataProduct não pode substituir a si mesmo')
+  } else if (config.replacedBy !== undefined) {
+    throw new TypeError('DataProduct ativo não pode declarar "replacedBy"')
+  }
+  return config
+}
+
+export function isDataProduct(value: unknown): value is DataProductConfig {
+  if (typeof value !== 'object' || value === null) return false
+  try {
+    defineDataProduct(value as DataProductConfig)
+    return true
+  } catch {
+    return false
+  }
+}

package/src/core/domain.ts

@@ -22,6 +22,7 @@
  */
 
 import type { ActionContract } from './contracts.ts'
+import type { DataProductConfig } from './data-product.ts'
 import { error } from './errors.ts'
 import type { ActionDef, ReactionDef, ScheduleDef } from './types.ts'
 
@@ -58,6 +59,9 @@ export interface DomainConfig {
    *  estrutural+negócio que vai pro manifest. */
   entities?: Record<string, unknown>
 
+  /** Produtos de Dados governados disponibilizados pelas Actions deste domínio. */
+  dataProducts?: Record<string, DataProductConfig> | DataProductConfig[]
+
   /** Repository class do domínio. */
   repository?: unknown
 
@@ -90,6 +94,7 @@ export interface FlattenedDomain {
   actions: ActionDef[]
   reactions: Array<ReactionDef<any>>
   schedules: ScheduleDef[]
+  dataProducts: DataProductConfig[]
 }
 
 // =============================================================================
@@ -150,6 +155,7 @@ export function isDomainConfig(value: unknown): value is DomainConfig {
     'subdomains' in v ||
     'dicts' in v ||
     'entities' in v ||
+    'dataProducts' in v ||
     'repository' in v ||
     'service' in v
   )
@@ -160,7 +166,7 @@ export function isDomainConfig(value: unknown): value is DomainConfig {
  * pro `Runtime.register`.
  */
 export function flattenDomain(domain: DomainConfig): FlattenedDomain {
-  const out: FlattenedDomain = { actions: [], reactions: [], schedules: [] }
+  const out: FlattenedDomain = { actions: [], reactions: [], schedules: [], dataProducts: [] }
   collect(domain, out)
   return out
 }
@@ -179,6 +185,12 @@ function collect(domain: DomainConfig, out: FlattenedDomain): void {
   if (domain.schedules !== undefined) {
     for (const schedule of domain.schedules) out.schedules.push(schedule)
   }
+  if (domain.dataProducts !== undefined) {
+    const products = Array.isArray(domain.dataProducts)
+      ? domain.dataProducts
+      : Object.values(domain.dataProducts)
+    for (const product of products) out.dataProducts.push(product)
+  }
   if (domain.subdomains !== undefined) {
     for (const sub of domain.subdomains) collect(sub, out)
   }
@@ -257,7 +269,7 @@ function validateDomain(domain: DomainConfig, path: string[]): void {
   // — actions: nomes únicos no domínio (e subdomínios) —
   // (Roda *depois* dos subdomains: assim erros de nome em subs aparecem
   // primeiro, antes de detectar duplicatas cruzadas.)
-  const collected: FlattenedDomain = { actions: [], reactions: [], schedules: [] }
+  const collected: FlattenedDomain = { actions: [], reactions: [], schedules: [], dataProducts: [] }
   collect(domain, collected)
 
   const actionNames = new Set<string>()
@@ -271,6 +283,48 @@ function validateDomain(domain: DomainConfig, path: string[]): void {
     }
     actionNames.add(action.name)
   }
+
+  const entityNames = new Set<string>()
+  const collectEntityNames = (current: DomainConfig): void => {
+    for (const [key, raw] of Object.entries(current.entities ?? {})) {
+      const declared = typeof raw === 'object' && raw !== null && 'name' in raw
+        ? (raw as { name?: unknown }).name
+        : undefined
+      entityNames.add(typeof declared === 'string' && declared !== '' ? declared : key)
+    }
+    for (const subdomain of current.subdomains ?? []) collectEntityNames(subdomain)
+  }
+  collectEntityNames(domain)
+
+  const productIds = new Set<string>()
+  for (const product of collected.dataProducts) {
+    if (productIds.has(product.id)) {
+      throw error({
+        code: 'domain.duplicate_data_product',
+        category: 'internal',
+        message: `DataProduct "${product.id}" duplicado em "${fullPathStr}"`,
+      })
+    }
+    productIds.add(product.id)
+    for (const actionName of product.interfaces) {
+      if (!actionNames.has(actionName)) {
+        throw error({
+          code: 'domain.data_product_interface_not_found',
+          category: 'internal',
+          message: `DataProduct "${product.id}" referencia a Action inexistente "${actionName}"`,
+        })
+      }
+    }
+    for (const entityName of product.entities) {
+      if (!entityNames.has(entityName)) {
+        throw error({
+          code: 'domain.data_product_entity_not_found',
+          category: 'internal',
+          message: `DataProduct "${product.id}" referencia a Entity inexistente "${entityName}"`,
+        })
+      }
+    }
+  }
 }
 
 /**

package/src/core/index.ts

@@ -200,6 +200,15 @@ export { defineSchedule, isSchedule } from './schedules.ts'
 export { defineDomain, flattenDomain, isDomainConfig } from './domain.ts'
 export type { DomainConfig, FlattenedDomain } from './domain.ts'
 
+// — Produtos de Dados ————————————————————————————————————————————————————————
+export { defineDataProduct, isDataProduct } from './data-product.ts'
+export type {
+  DataProductAccess,
+  DataProductConfig,
+  DataProductSource,
+  DataProductStatus,
+} from './data-product.ts'
+
 // — Audit —————————————————————————————————————————————————————————————————————
 export { AuditEmitter } from './audit.ts'
 

package/src/core/runtime.ts

@@ -16,6 +16,7 @@ import { isBackgroundAction } from './actions.ts'
 import { isSchedule } from './schedules.ts'
 import { collectDomainWarnings, flattenDomain, isDomainConfig } from './domain.ts'
 import type { DomainConfig } from './domain.ts'
+import type { DataProductConfig } from './data-product.ts'
 import { AuditEmitter } from './audit.ts'
 import { error, isActionError, normalizeError } from './errors.ts'
 import { normalizeTraceContext } from './trace.ts'
@@ -254,6 +255,8 @@ export class Runtime {
   private readonly actions = new Map<string, ActionDef>()
   private readonly reactions = new Map<string, ReactionDef<any>>()
   private readonly schedules = new Map<string, ScheduleDef>()
+  private readonly dataProducts = new Map<string, DataProductConfig>()
+  private readonly actionDataProducts = new Map<string, Set<string>>()
 
   /**
    * Map entidade → resolver, usado pra carregar specs DSL de loads
@@ -315,8 +318,8 @@ export class Runtime {
     for (const item of items) {
       if (isDomainConfig(item)) {
         collectDomainWarnings(item)
-        const { actions, reactions, schedules } = flattenDomain(item)
-        this.registerFlat(actions, reactions, schedules)
+        const { actions, reactions, schedules, dataProducts } = flattenDomain(item)
+        this.registerFlat(actions, reactions, schedules, dataProducts)
       } else if (isSchedule(item)) {
         this.registerSchedules([item])
       } else if (isReaction(item)) {
@@ -356,10 +359,31 @@ export class Runtime {
     actions: ActionDef[],
     reactions: Array<ReactionDef<any>>,
     schedules: ScheduleDef[],
+    dataProducts: DataProductConfig[],
   ): void {
     this.registerActions(actions)
     this.registerReactions(reactions)
     this.registerSchedules(schedules)
+    this.registerDataProducts(dataProducts)
+  }
+
+  private registerDataProducts(products: DataProductConfig[]): void {
+    for (const product of products) {
+      if (this.dataProducts.has(product.id)) {
+        throw error({
+          code: 'runtime.duplicate_data_product',
+          category: 'internal',
+          message: `DataProduct "${product.id}" registrado duas vezes`,
+        })
+      }
+      this.dataProducts.set(product.id, product)
+      for (const action of product.interfaces) {
+        const related = this.actionDataProducts.get(action) ?? new Set<string>()
+        related.add(product.id)
+        this.actionDataProducts.set(action, related)
+      }
+    }
+    this.aiToolsCache = null
   }
 
   private registerActions(actions: ActionDef[]): void {
@@ -795,6 +819,7 @@ export class Runtime {
         name: action.name,
         description: cfg.description ?? action.description ?? action.name,
         inputSchema: action.input,
+        metadata: { dataProducts: [...(this.actionDataProducts.get(action.name) ?? [])].sort() },
       })
     }
     this.aiToolsCache = tools

package/src/core/types.ts

@@ -1261,6 +1261,8 @@ export interface AiTool {
   name: string
   description: string
   inputSchema: unknown
+  /** Metadados de governança para o host; não fazem parte do prompt nem concedem acesso. */
+  metadata?: { dataProducts?: string[] }
 }
 
 /** Turno de conversa (histórico multi-turn do chat). */

package/src/mcp/index.ts

@@ -46,6 +46,7 @@ export function createOpusMcpServer(runtime: Runtime, opts: OpusMcpOptions = {})
       name: t.name,
       description: t.description,
       inputSchema: toJsonSchema(t.inputSchema) as { type: 'object' },
+      _meta: { 'com.softize.opus/data-products': t.metadata?.dataProducts ?? [] },
     })),
   }))
 

package/src/ui/components/primitives/chat.tsx

@@ -5,6 +5,10 @@ import { Composer } from './composer.tsx'
 import { Markdown } from './markdown.tsx'
 
 export interface ChatMessage {
+  /** Identidade persistida pelo app. Opcional para históricos legados. */
+  id?: string
+  /** Instante ISO-8601 persistido pelo app. Opcional para históricos legados. */
+  createdAt?: string
   role: 'user' | 'assistant'
   content: string
 }
@@ -19,8 +23,10 @@ export interface ChatArtifact {
 /** Item do transcript no modo CONTROLADO (o app é o dono do estado — ex.: sala
  *  server-autoritativa com replay, como o ChatRail do Maestro). */
 export type ChatTranscriptItem =
-  | { role: 'user' | 'assistant' | 'error'; content: string }
-  | { role: 'artifact'; artifact: ChatArtifact }
+  | { id?: string; createdAt?: string; role: 'user' | 'assistant' | 'error'; content: string }
+  | { id?: string; createdAt?: string; role: 'artifact'; artifact: ChatArtifact }
+
+export type ChatTranscriptMessage = Extract<ChatTranscriptItem, { content: string }>
 
 /** Feedback humano do tool em uso (default pt-BR; override por prop). */
 function defaultHumanizeTool(name: string): string {
@@ -85,6 +91,9 @@ export interface ChatProps {
   kickoff?: () => Promise<string> | AsyncIterable<ChatEvent>
   /** Render do evento `artifact` (card, iframe, preview…). Default: link com o título. */
   renderArtifact?: (artifact: ChatArtifact) => React.ReactNode
+  /** Ações contextuais de uma mensagem. O Chat fornece apenas a anatomia; buscar dados
+   *  detalhados, pedir reautorização e decidir o conteúdo pertencem ao app. */
+  renderMessageActions?: (message: ChatTranscriptMessage) => React.ReactNode
   /** Rótulo humano do tool em uso no indicador vivo (modo autogerenciado). */
   humanizeTool?: (name: string, detail?: string) => string
   placeholder?: string
@@ -95,6 +104,14 @@ function isAsyncIterable(value: unknown): value is AsyncIterable<ChatEvent> {
   return typeof value === 'object' && value !== null && Symbol.asyncIterator in value
 }
 
+function transcriptMeta(): { id: string; createdAt: string } {
+  const cryptoApi = globalThis.crypto
+  const id = typeof cryptoApi?.randomUUID === 'function'
+    ? cryptoApi.randomUUID()
+    : `message_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`
+  return { id, createdAt: new Date().toISOString() }
+}
+
 /** Agrupa o transcript em turnos (mensagem do usuário + o que veio em resposta). */
 function groupTurns(items: ChatTranscriptItem[]): Array<{ user: ChatTranscriptItem | null; rest: ChatTranscriptItem[] }> {
   const turns: Array<{ user: ChatTranscriptItem | null; rest: ChatTranscriptItem[] }> = []
@@ -114,6 +131,7 @@ interface ChatTranscriptProps {
   greeting: string | undefined
   empty: React.ReactNode | undefined
   renderArtifact: ChatProps['renderArtifact']
+  renderMessageActions: ChatProps['renderMessageActions']
 }
 
 /**
@@ -128,6 +146,7 @@ const ChatTranscript = React.memo(function ChatTranscript({
   greeting,
   empty,
   renderArtifact,
+  renderMessageActions,
 }: ChatTranscriptProps): React.ReactElement {
   const scrollRef = React.useRef<HTMLDivElement>(null)
   const turns = React.useMemo(() => groupTurns(items), [items])
@@ -164,16 +183,21 @@ const ChatTranscript = React.memo(function ChatTranscript({
         // (o agente narra o que vai fazendo), então andam juntas; quem separa é o gap
         // MAIOR entre turnos. Com o mesmo gap nos dois níveis, um turno de oito falas
         // curtas virava uma parede uniforme, sem começo nem fim visíveis.
-        <div key={ti} className="flex flex-col gap-1">
+        <div key={turn.user?.id ?? turn.rest[0]?.id ?? ti} className="flex flex-col gap-1">
           {turn.user !== null && turn.user.role === 'user' && (
-            <div data-slot="chat-turn-user" className="flex justify-end py-1.5">
+            <div
+              data-slot="chat-turn-user"
+              data-message-id={turn.user.id}
+              data-message-created-at={turn.user.createdAt}
+              className="flex justify-end py-1.5"
+            >
               <UserTurn content={turn.user.content} />
             </div>
           )}
           {turn.rest.map((item, i) => {
             if (item.role === 'artifact') {
               return (
-                <div key={i} data-slot="chat-artifact" className="flex justify-start">
+                <div key={item.id ?? i} data-slot="chat-artifact" data-message-id={item.id} className="flex justify-start">
                   {renderArtifact !== undefined ? (
                     renderArtifact(item.artifact)
                   ) : (
@@ -192,7 +216,9 @@ const ChatTranscript = React.memo(function ChatTranscript({
             if (item.role === 'error') {
               return (
                 <div
-                  key={i}
+                  key={item.id ?? i}
+                  data-slot="chat-error"
+                  data-message-id={item.id}
                   className="max-w-[88%] self-start rounded-xl border border-context-danger-border bg-context-danger-subtle px-3.5 py-2.5 text-sm text-context-danger-emphasis"
                 >
                   {item.content}
@@ -201,8 +227,22 @@ const ChatTranscript = React.memo(function ChatTranscript({
             }
             // O assistente responde direto no corpo, em Markdown (convenção da casa).
             return (
-              <div key={i} className="break-words px-1 text-sm leading-snug">
+              <div
+                key={item.id ?? i}
+                data-slot="chat-message"
+                data-message-id={item.id}
+                data-message-created-at={item.createdAt}
+                className="group/chat-message break-words px-1 text-sm leading-snug"
+              >
                 <Markdown content={item.content} />
+                {renderMessageActions !== undefined && (
+                  <div
+                    data-slot="chat-message-actions"
+                    className="mt-1 flex min-h-5 items-center opacity-0 transition-opacity group-hover/chat-message:opacity-100 focus-within:opacity-100"
+                  >
+                    {renderMessageActions(item)}
+                  </div>
+                )}
               </div>
             )
           })}
@@ -257,6 +297,7 @@ export function Chat({
   initialMessages,
   kickoff,
   renderArtifact,
+  renderMessageActions,
   humanizeTool = defaultHumanizeTool,
   placeholder = 'Escreva uma mensagem…',
   className,
@@ -335,7 +376,7 @@ export function Chat({
       return
     }
 
-    const next: ChatTranscriptItem[] = [...ownItems, { role: 'user', content: text }]
+    const next: ChatTranscriptItem[] = [...ownItems, { ...transcriptMeta(), role: 'user', content: text }]
     setOwnItems(next)
     const transcript = next.filter((i): i is ChatMessage => i.role === 'user' || i.role === 'assistant')
     await consume(() => send!(transcript))
@@ -349,16 +390,18 @@ export function Chat({
       const result = run()
       if (isAsyncIterable(result)) {
         let streaming = false
+        let streamingMeta: { id: string; createdAt: string } | undefined
         for await (const event of result) {
           if (event.type === 'text') {
             setOwnActivity(null)
             setOwnItems((list) => {
               const last = list[list.length - 1]
               if (streaming && last !== undefined && last.role === 'assistant') {
-                return [...list.slice(0, -1), { role: 'assistant', content: last.content + event.delta }]
+                return [...list.slice(0, -1), { ...last, content: last.content + event.delta }]
               }
               streaming = true
-              return [...list, { role: 'assistant', content: event.delta }]
+              streamingMeta = transcriptMeta()
+              return [...list, { ...streamingMeta, role: 'assistant', content: event.delta }]
             })
           } else if (event.type === 'tool') {
             streaming = false
@@ -367,20 +410,20 @@ export function Chat({
             streaming = false
             setOwnItems((list) => [
               ...list,
-              { role: 'artifact', artifact: { kind: event.kind, ref: event.ref, title: event.title } },
+              { ...transcriptMeta(), role: 'artifact', artifact: { kind: event.kind, ref: event.ref, title: event.title } },
             ])
           } else if (event.type === 'done') {
             if (!event.ok) {
-              setOwnItems((list) => [...list, { role: 'error', content: event.error ?? 'Desculpe, algo falhou.' }])
+              setOwnItems((list) => [...list, { ...transcriptMeta(), role: 'error', content: event.error ?? 'Desculpe, algo falhou.' }])
             }
           }
         }
       } else {
         const reply = await result
-        setOwnItems((list) => [...list, { role: 'assistant', content: reply }])
+        setOwnItems((list) => [...list, { ...transcriptMeta(), role: 'assistant', content: reply }])
       }
     } catch {
-      setOwnItems((list) => [...list, { role: 'error', content: 'Desculpe, algo falhou.' }])
+      setOwnItems((list) => [...list, { ...transcriptMeta(), role: 'error', content: 'Desculpe, algo falhou.' }])
     } finally {
       setOwnBusy(false)
       setOwnActivity(null)
@@ -395,6 +438,7 @@ export function Chat({
         greeting={greeting}
         empty={empty}
         renderArtifact={renderArtifact}
+        renderMessageActions={renderMessageActions}
       />
       {/* Composer da casa (pílula elevada, enviar dentro). Extraído no <Composer> — o Chat
           liga texto/envio e repassa `composerActions` pros seletores da conversa (agente,

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

@@ -92,6 +92,11 @@ Reidratação: passe `initialMessages` com o histórico persistido e troque a `k
 componente ao trocar de conversa. O rótulo do indicador é customizável por
 `humanizeTool={(name) => '…'}`.
 
+Itens controlados podem carregar `id` e `createdAt`. O Chat os projeta no elemento da
+mensagem e oferece `renderMessageActions` para ações contextuais discretas. O slot não
+busca nem conhece detalhes: o app deve carregar informação complementar somente após a
+interação da pessoa e aplicar novamente sua autorização.
+
 ## Propriedades de Chat
 
 | Propriedade | Tipo | Padrão | Descrição |
@@ -109,5 +114,6 @@ componente ao trocar de conversa. O rótulo do indicador é customizável por
 | `initialMessages` | `ChatMessage[]` | | Histórico inicial do modo autogerenciado; troque a `key` ao trocar de conversa. |
 | `kickoff` | `() => Promise<string> \| AsyncIterable<ChatEvent>` | | Conversa que começa pelo assistente, uma vez, quando o transcript nasce vazio. |
 | `renderArtifact` | `(artifact: ChatArtifact) => ReactNode` | link com o título | Render do evento `artifact`. |
+| `renderMessageActions` | `(message: ChatTranscriptMessage) => ReactNode` | | Ações contextuais da mensagem; ficam visíveis em hover ou foco. |
 | `humanizeTool` | `(name: string, detail?: string) => string` | pt-BR embutido | Rótulo humano do tool em uso no indicador vivo. |
 | `placeholder` | `string` | `'Escreva uma mensagem…'` | Placeholder do composer. |

package/src/ui/react.tsx

@@ -33,6 +33,7 @@ export type {
   ChatMessage,
   ChatArtifact,
   ChatTranscriptItem,
+  ChatTranscriptMessage,
 } from "./components/primitives/chat.tsx";
 export { Ask } from "./components/primitives/ask.tsx";
 export type { AskProps } from "./components/primitives/ask.tsx";