@softize/opus 15.0.1 → 15.2.0

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.0.1",
+  "version": "15.2.0",
   "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/registry/skills/build-opus-ui/references/ui-patterns.md

@@ -10,6 +10,9 @@
   para o caso direto.
   Não misturar as duas formas. Alterar `className` apenas quando a superfície tiver uma necessidade
   real de largura; não reconstruir esse container em cada rota.
+- Fora de `PageShell`, a composição explícita também pode trocar `PageHeader` por `PageIntro` quando
+  o conteúdo precisar somente de título, descrição e ações, sem retorno ou breadcrumb. `PageIntro`
+  dá mais presença ao título e não é uma abreviação visual de `PageHeader`.
 - `PageHeader` é a única região de cabeçalho da página. O default acompanha o container;
   `variant="bar"` apresenta a mesma anatomia como faixa compacta no topo. Em uma subpágina simples,
   `PageBack` recebe o destino pai explícito: aparece acima do título no default e como icon-only com
@@ -17,10 +20,17 @@
   `PageNavigation`. Não combine retorno e breadcrumb nem crie um chrome paralelo para uma `Page`.
   Ações com texto na barra usam `Button size="sm"`; ações somente com ícone usam `icon-sm`.
   `PageActionsTarget` fica reservado a workspaces imersivos que já possuam chrome próprio.
+- Quando shell e rota conhecem partes diferentes da mesma página, use `PageShell` ao redor da rota.
+  O shell fornece `navigation`; a `Page` descendente continua declarando `title`, `description` e
+  `actions`. O Opus mantém a barra de `3rem`, projeta as ações nela e apresenta título e descrição
+  como `PageIntro` no conteúdo. Na forma explícita dentro do shell, use
+  `Page > PageIntro (PageTitle, PageDescription?, PageActions?) + PageBody`. Não monte `PaneHeader`,
+  portal ou seletor global para reconstruir essa composição.
 - `PageState` substitui todo o conteúdo principal quando a página carrega, falha ou está vazia. Na
   forma curta ele pode ser escrito como filho direto de `Page`, que cria o `PageBody`; na forma
-  explícita, fica sozinho dentro de `PageBody`. Nos três estados ativos, o cabeçalho some inteiro —
-  incluindo o `PageBack` —, o estado ocupa a área disponível e seu título assume o heading
+  explícita, fica sozinho dentro de `PageBody`. Nos três estados ativos, o cabeçalho da Page isolada
+  some inteiro — incluindo o `PageBack`; dentro de `PageShell`, somente `PageIntro` some e a barra
+  permanece. O estado ocupa a área disponível e seu título assume o heading
   principal, inclusive quando um componente intermediário renderiza o estado. Uma subpágina que
   dependa do retorno ao pai oferece essa saída pelo `action` do próprio `PageState`. O erro mantém
   `role="alert"`, usa a mesma composição central e sem moldura dos demais estados e apresenta a

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 ?? [] },
     })),
   }))