@softize/opus 15.2.1 → 16.0.0

package/docs/adr/0012-modal-header-only-names-the-surface.md

@@ -0,0 +1,45 @@
+# ADR 0012 — O cabeçalho modal apenas nomeia a superfície
+
+- **Status:** aceita.
+- **Data:** 2026-09-11.
+
+## Contexto
+
+`DialogDescription` e `DrawerDescription` tornavam natural preencher o cabeçalho com uma segunda
+linha mesmo quando ela apenas repetia o título ou explicava a ação óbvia. O resultado era uma
+hierarquia mais pesada, mais espaço fixo antes da tarefa e textos que raramente ajudavam a pessoa a
+decidir.
+
+Há, porém, contexto que não pode desaparecer: consequências, restrições e instruções que mudam a
+decisão. Esse conteúdo pertence à tarefa, não ao nome da superfície. Também pode precisar participar
+da descrição acessível do modal.
+
+## Decisão
+
+- `DialogHeader` e `DrawerHeader` contêm o título e, quando necessário, mídia. Não existe API pública
+  `DialogDescription` ou `DrawerDescription`.
+- Contexto relevante aparece no início de `DialogBody` ou `DrawerBody`, como texto, `Alert` ou uma
+  composição própria. Texto que apenas repete o título ou a ação é omitido.
+- A API imperativa usa somente `body` para esse conteúdo. `ActionFormDialog` e `ActionListDialog`
+  oferecem `intro` no início do corpo; não oferecem `description`.
+- `DialogContent` e `DrawerContent` não inferem uma descrição. Quando um trecho conciso do corpo deve
+  descrever a superfície para tecnologias assistivas, o consumidor relaciona seu `id` por
+  `aria-describedby`.
+- `CommandDialog` mantém internamente uma instrução apenas para tecnologias assistivas, porque ela
+  explica o funcionamento do controle e não é copy visual do cabeçalho.
+
+## Consequências
+
+- Modais comuns começam mais perto da tarefa e não pedem texto de preenchimento.
+- Informações importantes continuam visíveis, mas ocupam a região rolável e podem usar o componente
+  semântico adequado.
+- A migração troca `description` por `body` na API imperativa, por `intro` nos wrappers e move conteúdo
+  declarativo relevante para o começo do corpo.
+- O checker reprova as APIs removidas com orientação de migração.
+
+## Verificação
+
+- o barrel público não exporta `DialogDescription` nem `DrawerDescription`;
+- os tipos das APIs imperativas não aceitam `description`;
+- testes cobrem `body`, `intro`, a relação acessível e os diagnósticos de migração;
+- a auditoria de docs, o inventário de copy, o typecheck e a suíte do pacote permanecem verdes.

package/docs/adr/0013-presentation-is-a-portable-action-oriented-artifact.md

@@ -0,0 +1,92 @@
+# ADR 0013 — Presentation é um artefato portátil orientado a actions
+
+- **Status:** aceita.
+- **Data:** 2026-09-11.
+
+## Contexto
+
+Page, Dialog e Drawer compartilham uma anatomia estrutural, mas consumidores ainda repetem a
+coordenação entre título, navegação, corpo, ações, estados e ciclo de abertura. Essa repetição
+dificulta apresentar o mesmo recurso em superfícies diferentes e impede que ferramentas analisem
+a interface antes de executar React.
+
+O Opus já declara actions `simple`, `form`, `list` e `view`. Um artefato de interface não deve
+reimplementar seus contratos, validação, autorização ou transporte; deve apenas compor essas
+capacidade em uma apresentação verificável.
+
+## Decisão
+
+`Presentation` é o artefato declarativo que descreve um recurso independentemente da superfície em
+que aparece. `Surface` escolhe `page`, `dialog` ou `drawer` no momento da renderização.
+
+A anatomia portátil é `Header + Body + Footer?`. O header organiza horizontalmente
+`Navigation? + Title + Actions?`; o body contém o recurso; o footer contém ações de conclusão.
+Dialog e Drawer acrescentam o fechamento ao final das ações do header. Page pode ainda usar
+navegação persistente fornecida pelo shell e uma introdução opcional dentro do body, sem mover nem
+duplicar o título estrutural.
+
+Uma action assume um de dois papéis:
+
+- conteúdo no body: actions `form`, `list` e `view` usam seus patterns canônicos;
+- comando no header ou footer: `simple` executa por `ActionTrigger`; os demais kinds abrem ou
+  navegam para outra Presentation que os apresenta como conteúdo.
+
+O kind declarado pela action determina o pattern. A Presentation não repete `presentation: form`
+ou `presentation: trigger`. Bindings declarativos fornecem input a partir de rota, registro, item,
+seleção, sessão, resultado, valor fixo ou relógio. Autorização permanece no servidor.
+
+Efeitos posteriores e coordenação de bloqueio são dados declarativos, não callbacks persistidos. O
+renderer pode coordenar os escopos `action`, `group` e `surface`, mas cada pattern continua dono de
+loading, erro, vazio, validação e repetição próprios.
+
+Presentations possuem identificador e versão de schema, são registradas no `opus.config.ts` e
+projetadas no manifest. A lens lê essa projeção; não infere a interface pelo JSX. Combinações
+inválidas, referências ausentes e bindings incompatíveis produzem diagnósticos antes do runtime.
+
+`PresentationDefinition` e `PresentationInvocation` têm ciclos de vida distintos. A definição é
+estática, publicável no manifest e inspecionável pela Lens. A invocação é o estado serializável de
+uma execução: identifica a Presentation, escolhe a surface, carrega somente input JSON e mantém a
+pilha de frames necessária para voltar. Ela não é publicada no manifest.
+
+`back` restaura o último frame da pilha. `close` encerra apenas dialog ou drawer e é inválido para
+page. `navigate` abre outra invocação por push ou substitui a atual; sincronizar esse estado com URL
+é responsabilidade do adaptador da aplicação quando refresh, deep link ou histórico forem
+necessários. O inspetor de desenvolvimento reúne definição, invocação, bindings resolvidos e
+diagnósticos, mascarando chaves sensíveis antes de expor o JSON.
+
+## Consequências
+
+- O mesmo recurso pode ser apresentado como page, dialog ou drawer sem três implementações.
+- Novas interfaces convencionais concentram código na declaração e na composição específica.
+- `ActionFormDialog`, `ActionListDialog` e wrappers equivalentes permanecem atalhos manuais, mas não
+  formam novos kinds do artefato.
+- Interfaces específicas continuam possíveis por nós de extensão explícitos; uma extensão não é
+  considerada portátil até possuir renderer registrado para as superfícies declaradas.
+- O schema evolui por versão e migração; consumidores não dependem de detalhes internos do renderer.
+
+## Alternativas consideradas
+
+### Persistir JSX ou callbacks
+
+Preservaria liberdade irrestrita, mas não seria serializável, verificável nem seguro para autoria
+por ferramentas. Foi descartada em favor de bindings e efeitos fechados.
+
+### Criar schemas separados para Page, Dialog e Drawer
+
+Representaria diretamente a aparência atual, mas triplicaria a composição e faria a superfície
+definir o recurso. Foi descartada porque as diferenças pertencem ao renderer.
+
+### Tratar toda action como ActionTrigger
+
+Uniformizaria comandos visualmente, mas perderia os ciclos próprios de formulário, lista e view.
+Foi descartada porque compatibilidade exige delegar cada kind ao pattern canônico.
+
+## Verificação
+
+- testes de schema cobrem versão, referências, kinds, placements e bindings;
+- testes do renderer exercitam `simple`, `form`, `list` e `view` nas superfícies válidas;
+- o manifest projeta Presentations sem callbacks nem dados server-only;
+- a lens lista e expõe o JSON integral de cada Presentation;
+- testes de invocação cobrem push, replace, back, close e rejeição de input não JSON;
+- o inspetor mascara segredo, token, cookie, autorização, senha e chave de API;
+- uma aplicação consumidora usa o pacote local por symlink durante a migração página por página.

package/docs/code-style.md

@@ -61,7 +61,12 @@ Base instalada é dona do catálogo, dos kinds aceitos e do fundamento de cada r
     "allowedUppercase": ["CPF"],
     "exclude": ["scripts/fixtures/**"],
     "transforms": [
-      { "source": "src/account.ts", "line": 12, "role": "button", "transform": "uppercase" }
+      {
+        "source": "src/account.ts",
+        "line": 12,
+        "role": "button",
+        "transform": "uppercase"
+      }
     ],
     "exemptions": [
       {
@@ -78,24 +83,24 @@ Base instalada é dona do catálogo, dos kinds aceitos e do fundamento de cada r
 }
 ```
 
-| Propriedade Opus | Papel no protocolo Base |
-|---|---|
-| `label`, `confirm.*Label`, `ActionTrigger.label` | `button` |
-| `title`, `examples[].name` | `title` |
-| `summary`, `description`, `examples[].description`, `expand.*.description` | `description` |
-| `messages.success`, `messages.error`, `messages.confirmation` | `success`, `error`, `message` |
-| `confirm.message` | `dialog-body` |
-| `fields.*.label`, `filters.*.label` | `label` |
-| `placeholder`, `help` | `placeholder`, `helper-text` |
-| opções estáticas | `menu-item` |
-| `columns[].label`, `periods[].label` | `heading`, `tab` |
-| `Select.emptyText`, `Select.searchPlaceholder` | `empty-state`, `placeholder` |
-| `Select.options[].hint/triggerLabel/group` | `label`, `label`, `heading` |
-| `ActionTrigger.confirm.*` | papel correspondente do diálogo |
-| `t.dict` — `label`, `description`, `doc` das entradas e `doc` do dicionário | `label`, `description` |
+| Propriedade Opus                                                                                                                                                                           | Papel no protocolo Base                                  |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------- |
+| `label`, `confirm.*Label`, `ActionTrigger.label`                                                                                                                                           | `button`                                                 |
+| `title`, `examples[].name`                                                                                                                                                                 | `title`                                                  |
+| `summary`, `description`, `examples[].description`, `expand.*.description`                                                                                                                 | `description`                                            |
+| `messages.success`, `messages.error`, `messages.confirmation`                                                                                                                              | `success`, `error`, `message`                            |
+| `confirm.message`                                                                                                                                                                          | `dialog-body`                                            |
+| `fields.*.label`, `filters.*.label`                                                                                                                                                        | `label`                                                  |
+| `placeholder`, `help`                                                                                                                                                                      | `placeholder`, `helper-text`                             |
+| opções estáticas                                                                                                                                                                           | `menu-item`                                              |
+| `columns[].label`, `periods[].label`                                                                                                                                                       | `heading`, `tab`                                         |
+| `Select.emptyText`, `Select.searchPlaceholder`                                                                                                                                             | `empty-state`, `placeholder`                             |
+| `Select.options[].hint/triggerLabel/group`                                                                                                                                                 | `label`, `label`, `heading`                              |
+| `ActionTrigger.confirm.*`                                                                                                                                                                  | papel correspondente do diálogo                          |
+| `t.dict` — `label`, `description`, `doc` das entradas e `doc` do dicionário                                                                                                                | `label`, `description`                                   |
 | `DataState`/`PageState`/`ActionList`/`ActionListDialog` — `emptyMessage`, `errorMessage`, `retryLabel`; `PageState`/`ActionListDialog` — `title`, `description`; `ActionView.emptyMessage` | `empty-state`, `error`, `button`, `title`, `description` |
-| `dialog.alert/confirm/prompt/choose()` — `title`, `description`, `body`, `action`, `cancel`, `placeholder`, `actions[].label` | papel correspondente do diálogo |
-| `TooltipContent` (children), `LabelHelp.help` | `label`, `helper-text` |
+| `dialog.alert/confirm/prompt/choose()` — `title`, `description`, `body`, `action`, `cancel`, `placeholder`, `actions[].label`                                                              | papel correspondente do diálogo                          |
+| `TooltipContent` (children), `LabelHelp.help`                                                                                                                                              | `label`, `helper-text`                                   |
 
 ## Cobertura e significado do gate verde
 
@@ -109,7 +114,7 @@ O extrator cobre três superfícies, sem heurística de nome:
    `@softize/opus/schema/zod`; metadata livre não é classificada por nome, declarações dinâmicas
    reprovam em vez de serem executadas e o dicionário mantém um snapshot imutável das entradas;
 3. texto estático em filhos e props de uma allowlist de componentes importados diretamente
-   de `@softize/opus/ui*` — por exemplo, `Button`, `DialogTitle`, `DialogDescription`,
+   de `@softize/opus/ui*` — por exemplo, `Button`, `DialogTitle`, `DialogBody`,
    `FieldLabel`, `TabsTrigger`, `Page`, `Input` e `DataState`. Alias e namespace de import
    continuam rastreáveis. `uppercase`, variantes como `sm:hover:uppercase`, modificadores
    `!uppercase`/`uppercase!` e classes em descendentes são projetados na superfície que

package/docs/data-products.md

@@ -24,7 +24,7 @@ export const salesLeads = defineDataProduct({
   sources: [{ id: 'followize', label: 'Followize' }],
   entities: ['Lead'],
   access: {
-    contexts: ['sales'],
+    permissionContexts: ['sales'],
     organizationalScopes: ['unit', 'team'],
   },
   interfaces: ['sale.list', 'sales.performance'],
@@ -49,6 +49,12 @@ que uma interface deveria respeitar, por exemplo, unidade e equipe. Não é RLS
 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.
 
+`permissionContexts` nomeia especificamente chaves do vocabulário de permissão. Ele não descreve
+domínio de dados, Área, departamento nem contexto de tela; projetos que não adotam essa dimensão
+declaram uma lista vazia. O alias `contexts`, publicado originalmente na série 15.x, permanece
+aceito na entrada e projetado no manifest apenas para compatibilidade. Novas declarações e
+consumidores usam o nome qualificado; o alias só poderá ser removido numa versão major.
+
 ## Projeções
 
 `opus gen` publica os produtos no `.opus/manifest.json`. Actions expostas como tools carregam os

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softize/opus",
-  "version": "15.2.1",
+  "version": "16.0.0",
   "description": "End-to-end action protocol for TypeScript. Single package with subpath exports (core + adapters).",
   "license": "MIT",
   "type": "module",
@@ -153,6 +153,10 @@
       "types": "./src/seed/index.ts",
       "default": "./src/seed/index.ts"
     },
+    "./presentation": {
+      "types": "./src/presentation/index.ts",
+      "default": "./src/presentation/index.ts"
+    },
     "./server": {
       "types": "./src/server/index.ts",
       "default": "./src/server/index.ts"
@@ -212,17 +216,6 @@
   "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",
@@ -368,11 +361,21 @@
     "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"
-}
+  "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"
+  }
+}

package/registry/skills/build-opus-ui/references/ui-patterns.md

@@ -6,26 +6,29 @@
 - URL representa estado que precisa sobreviver a refresh, deep link ou histórico.
 - `Page` fornece o `<main>` e o container centralizado com teto padrão de `80rem`. Sua forma
   explícita é `Page > PageHeader (PageBack? | PageNavigation?, PageTitle, PageDescription?,
-  PageActions?) + PageBody`; `title`, `description` e `actions` no próprio `Page` são a abreviação
+PageActions?) + PageBody`; `title`, `description` e `actions` no próprio `Page` são a abreviação
   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
-  tooltip na barra. Para mais de um ancestral relevante, use `Breadcrumb` dentro de
-  `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.
+- `PageHeader` é a região de cabeçalho dentro de uma `Page` isolada e organiza navegação, título e
+  ações na mesma linha. Em uma subpágina simples, `PageBack` recebe o destino pai explícito e aparece
+  antes do título como controle somente com ícone. Para mais de um ancestral relevante, use
+  `Breadcrumb` dentro de `PageNavigation`. Não combine retorno e breadcrumb nem crie um chrome
+  paralelo para uma `Page`. `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.
+  O shell é o único responsável pela barra: 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. Ações com texto na barra
+  usam `Button size="sm"`; ações somente com ícone usam `icon-sm`. 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.
+- Quando a rota precisa de navegação própria além da navegação persistente do shell, declare
+  `PageNavigation` no `PageIntro`. Esse slot permanece com o recurso ao alternar entre Page, Dialog
+  e Drawer; não replique nele a navegação global já fornecida pelo shell.
 - `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 da Page isolada
@@ -37,7 +40,7 @@
   recuperação como botão `outline` textual. Estados de seção ou coleção continuam em `DataState`,
   `ActionView`, `ActionList` ou `Alert`; não elevar uma falha parcial a estado da página.
 - `Content` delimita uma seção e segue a mesma anatomia: `Content > ContentHeader (ContentTitle,
-  ContentDescription, ContentMeta, ContentActions) + ContentBody`. `ContentHeader` nunca fica
+ContentDescription, ContentMeta, ContentActions) + ContentBody`. `ContentHeader` nunca fica
   solto. `title`, `description`, `count` e `actions` no `Content` são a abreviação para o caso
   direto e não podem ser misturados ao header explícito. `level` preserva a hierarquia semântica
   do heading.
@@ -64,6 +67,11 @@
   controles customizados pelo contexto. `ActionFormCard` e `ActionFormDialog` acrescentam a
   casca; não duplicar o form para obter card ou modal. Cancelamento em forms, confirmações e
   modais usa `ghost`, deixando o destaque visual para a ação principal.
+- Cabeçalhos de `Dialog` e `Drawer` apenas nomeiam a superfície com o título. Não preencher uma
+  segunda linha por hábito. Consequência, restrição ou instrução que realmente mude a tarefa entra
+  no início de `DialogBody`/`DrawerBody`, como texto ou `Alert`; wrappers usam `intro` e a API
+  imperativa usa `body`. Relacione texto conciso por `aria-describedby` somente quando ele também
+  precisar descrever a superfície para tecnologias assistivas.
 - `ActionList` mantém fetch, toolbar, loading, erro, retry, vazio, seleção e paginação enquanto
   permite três composições de resultado: tabela por `columns`, renderer completo por `children`
   ou views nomeadas. Usar `ActionFilterBar` isoladamente só quando outra superfície assumir a
@@ -100,12 +108,12 @@
 O dicionário declara o papel; a tela só escolhe onde o valor fica. Tabela de decisão aplicada
 por `DictionaryValue` e pelas colunas de `ActionList`:
 
-| Papel declarado | Exemplos | Forma | Contexto | Variante | Ícone | Tooltip |
-|---|---|---|---|---|---|---|
-| `classification` | Tipo de cliente, categoria, natureza | Badge | `neutral` | `outline`; ignora `context` da entrada | se a entrada declara `icon` do catálogo | se `description` acrescenta ao rótulo |
-| `status` | Aberto, resolvido, degradado | Badge | pela entrada; `neutral` por padrão | `subtle`; nunca `outline` | idem | idem |
-| `stage` | Prospect, cliente; etapa do funil | Badge | igual a `status` | `subtle` | idem | idem |
-| `plain` ou ausente | Fonte, formato, período | Texto | — | — | idem | idem |
+| Papel declarado    | Exemplos                             | Forma | Contexto                           | Variante                               | Ícone                                   | Tooltip                               |
+| ------------------ | ------------------------------------ | ----- | ---------------------------------- | -------------------------------------- | --------------------------------------- | ------------------------------------- |
+| `classification`   | Tipo de cliente, categoria, natureza | Badge | `neutral`                          | `outline`; ignora `context` da entrada | se a entrada declara `icon` do catálogo | se `description` acrescenta ao rótulo |
+| `status`           | Aberto, resolvido, degradado         | Badge | pela entrada; `neutral` por padrão | `subtle`; nunca `outline`              | idem                                    | idem                                  |
+| `stage`            | Prospect, cliente; etapa do funil    | Badge | igual a `status`                   | `subtle`                               | idem                                    | idem                                  |
+| `plain` ou ausente | Fonte, formato, período              | Texto | —                                  | —                                      | idem                                    | idem                                  |
 
 Regras que não dependem da tabela:
 
@@ -123,13 +131,22 @@ Exemplo correto — tipo e estágio em colunas próprias, apresentação do dici
 
 ```ts
 export const customerKindDict = t.dict(
-  { pf: { label: 'Pessoa física', icon: 'user' }, pj: { label: 'Empresa', icon: 'building' } },
-  { doc: 'Natureza da parte no cadastro global.', presentation: 'classification' },
-)
+  {
+    pf: { label: "Pessoa física", icon: "user" },
+    pj: { label: "Empresa", icon: "building" },
+  },
+  {
+    doc: "Natureza da parte no cadastro global.",
+    presentation: "classification",
+  },
+);
 export const customerStageDict = t.dict(
-  { prospect: { label: 'Prospect' }, customer: { label: 'Cliente', context: 'success' } },
-  { doc: 'Estágio comercial atual da parte.', presentation: 'stage' },
-)
+  {
+    prospect: { label: "Prospect" },
+    customer: { label: "Cliente", context: "success" },
+  },
+  { doc: "Estágio comercial atual da parte.", presentation: "stage" },
+);
 // contrato:
 //   columns: [{ key: 'name' }, { key: 'kind', label: 'Tipo' }, { key: 'stage', label: 'Estágio' }]
 //   output: z.object({ kind: customerKindDict.zod(), stage: customerStageDict.zod() })

package/src/core/data-product.ts

@@ -14,12 +14,21 @@ export interface DataProductSource {
 }
 
 export interface DataProductAccess {
-  /** Contextos de dados normalmente exigidos pelas interfaces do produto. Descritivo. */
+  /** @deprecated Use `permissionContexts`; este alias será removido numa versão major. */
   contexts: readonly string[]
+  /** Nome qualificado dos contextos de permissão. Sempre presente após `defineDataProduct`. */
+  permissionContexts?: readonly string[]
   /** Eixos organizacionais que as Actions precisam considerar, como unit e team. Descritivo. */
   organizationalScopes: readonly string[]
 }
 
+export interface DataProductAccessInput {
+  permissionContexts?: readonly string[]
+  /** @deprecated Use `permissionContexts`; este alias será removido numa versão major. */
+  contexts?: readonly string[]
+  organizationalScopes: readonly string[]
+}
+
 export interface DataProductConfig {
   /** Identidade estável e namespaced, como `sales.leads`. */
   id: string
@@ -46,6 +55,19 @@ export interface DataProductConfig {
   replacedBy?: string
 }
 
+export type DataProductInput = Omit<DataProductConfig, 'access'> & { access: DataProductAccessInput }
+type PermissionContextsOf<T extends DataProductAccessInput> = Extract<
+  | ('permissionContexts' extends keyof T ? T['permissionContexts'] : never)
+  | ('contexts' extends keyof T ? T['contexts'] : never),
+  readonly string[]
+>
+export type DefinedDataProduct<T extends DataProductInput = DataProductInput> = Omit<T, 'access'> & {
+  access: Omit<T['access'], 'contexts' | 'permissionContexts'> & DataProductAccess & {
+    contexts: PermissionContextsOf<T['access']>
+    permissionContexts: PermissionContextsOf<T['access']>
+  }
+}
+
 const ID_RE = /^[a-z][a-z0-9_-]*(?:\.[a-z][a-z0-9_-]*)+$/
 
 function nonEmpty(value: unknown, field: string): void {
@@ -55,7 +77,7 @@ function nonEmpty(value: unknown, field: string): void {
 }
 
 /** 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 {
+export function defineDataProduct<const T extends DataProductInput>(config: T): DefinedDataProduct<T> {
   if (!ID_RE.test(config.id)) {
     throw new TypeError(`DataProduct id "${config.id}" deve ser namespaced e casar com ${ID_RE.source}`)
   }
@@ -90,10 +112,23 @@ export function defineDataProduct<const T extends DataProductConfig>(config: T):
     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')
+  const hasPermissionContexts = Array.isArray(config.access?.permissionContexts)
+  const hasLegacyContexts = Array.isArray(config.access?.contexts)
+  if ((!hasPermissionContexts && !hasLegacyContexts) || !Array.isArray(config.access?.organizationalScopes)) {
+    throw new TypeError('DataProduct "access" deve declarar permissionContexts e organizationalScopes')
+  }
+  if (
+    hasPermissionContexts &&
+    hasLegacyContexts &&
+    (config.access.permissionContexts!.length !== config.access.contexts!.length ||
+      config.access.permissionContexts!.some((context, index) => context !== config.access.contexts![index]))
+  ) {
+    throw new TypeError('DataProduct "access" recebeu permissionContexts e contexts divergentes')
   }
-  for (const context of config.access.contexts) nonEmpty(context, 'access.contexts[]')
+  const permissionContexts = (
+    hasPermissionContexts ? config.access.permissionContexts : config.access.contexts
+  ) as PermissionContextsOf<T['access']>
+  for (const context of permissionContexts) nonEmpty(context, 'access.permissionContexts[]')
   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"')
@@ -107,13 +142,22 @@ export function defineDataProduct<const T extends DataProductConfig>(config: T):
   } else if (config.replacedBy !== undefined) {
     throw new TypeError('DataProduct ativo não pode declarar "replacedBy"')
   }
-  return config
+  return {
+    ...config,
+    access: {
+      ...config.access,
+      permissionContexts,
+      contexts: permissionContexts,
+    },
+  } as unknown as DefinedDataProduct<T>
 }
 
 export function isDataProduct(value: unknown): value is DataProductConfig {
   if (typeof value !== 'object' || value === null) return false
+  const access = (value as { access?: { contexts?: unknown } }).access
+  if (!Array.isArray(access?.contexts)) return false
   try {
-    defineDataProduct(value as DataProductConfig)
+    defineDataProduct(value as DataProductInput)
     return true
   } catch {
     return false

package/src/core/index.ts

@@ -204,7 +204,10 @@ export type { DomainConfig, FlattenedDomain } from './domain.ts'
 export { defineDataProduct, isDataProduct } from './data-product.ts'
 export type {
   DataProductAccess,
+  DataProductAccessInput,
   DataProductConfig,
+  DataProductInput,
+  DefinedDataProduct,
   DataProductSource,
   DataProductStatus,
 } from './data-product.ts'