@softize/opus 15.0.1 → 15.2.0

package/CHANGELOG.md

@@ -7,6 +7,39 @@ 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.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
+página. O shell fornece a navegação e mantém uma barra de `3rem`; a `Page` descendente continua
+declarando título, descrição, ações e estados. As ações aparecem na barra sem portal montado pelo
+consumidor, enquanto título e descrição formam o novo `PageIntro` dentro do conteúdo.
+
+Em um estado integral, `PageShell` permanece visível e somente `PageIntro` é ocultado. A composição
+anterior de `Page`, `PageHeader` e `PageBody` não muda fora do shell. `PageActionsTarget` continua
+disponível para workspaces imersivos que já possuem uma moldura própria.
+
+**Migração opcional:** substitua barras paralelas e seletores que escondem slots por
+`PageShell navigation={...}` ao redor da rota. A página interna pode continuar na forma curta; use
+`PageIntro` e `PageBody` somente quando precisar da composição explícita.
+
 ## 15.0.1 — 2026-09-09
 
 Correções sobre a 15.0.0, publicada horas antes, todas vindas da revisão dela. Nenhuma novidade de

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

@@ -105,12 +105,13 @@ const UI_SURFACE_PAIRS = new Map([
 // locais homônimos.
 const UI_STRUCTURAL_PARENTS = new Map([
   ["PageHeader", new Set(["Page"])],
+  ["PageIntro", new Set(["Page"])],
   ["PageBody", new Set(["Page"])],
-  ["PageTitle", new Set(["PageHeader"])],
+  ["PageTitle", new Set(["PageHeader", "PageIntro"])],
   ["PageBack", new Set(["PageHeader"])],
   ["PageNavigation", new Set(["PageHeader"])],
-  ["PageDescription", new Set(["PageHeader"])],
-  ["PageActions", new Set(["PageHeader"])],
+  ["PageDescription", new Set(["PageHeader", "PageIntro"])],
+  ["PageActions", new Set(["PageHeader", "PageIntro"])],
   ["ContentHeader", new Set(["Content"])],
   ["ContentBody", new Set(["Content"])],
   ["ContentTitle", new Set(["ContentHeader"])],
@@ -166,6 +167,7 @@ const UI_STRUCTURAL_ROOTS = new Map([
     "Page",
     {
       header: "PageHeader",
+      alternateHeader: "PageIntro",
       body: "PageBody",
       shorthand: new Set(["title", "description", "actions"]),
       // O contador saiu do título da página (ADR 0009). Tirar `count` do shorthand não proíbe
@@ -187,6 +189,7 @@ const UI_STRUCTURAL_ROOTS = new Map([
 
 const UI_STRICT_DIRECT_COMPONENTS = new Set([
   "PageHeader",
+  "PageIntro",
   "PageBody",
   "PageTitle",
   "PageBack",
@@ -204,6 +207,8 @@ const UI_STRICT_DIRECT_COMPONENTS = new Set([
   "AlertActions",
 ]);
 
+const UI_STRUCTURAL_CONTAINERS = new Set(["PageShell"]);
+
 const UI_STRUCTURAL_HEADERS = new Map([
   [
     "PageHeader",
@@ -219,6 +224,14 @@ const UI_STRUCTURAL_HEADERS = new Map([
       shorthand: new Set(),
     },
   ],
+  [
+    "PageIntro",
+    {
+      title: "PageTitle",
+      optional: new Set(["PageDescription", "PageActions"]),
+      shorthand: new Set(),
+    },
+  ],
   [
     "ContentHeader",
     {
@@ -310,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 —
@@ -503,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,
@@ -519,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;
@@ -542,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
@@ -793,6 +895,7 @@ function structuralJsxAncestorName(node, imports) {
       if (
         imported !== undefined &&
         (UI_STRUCTURAL_ROOTS.has(imported) ||
+          UI_STRUCTURAL_CONTAINERS.has(imported) ||
           UI_STRUCTURAL_PARENTS.has(imported) ||
           [...UI_STRUCTURAL_PARENTS.values()].some((parents) =>
             parents.has(imported),
@@ -805,6 +908,18 @@ function structuralJsxAncestorName(node, imports) {
   return null;
 }
 
+function hasJsxAncestor(node, imports, component) {
+  let current = node.parent;
+  while (current !== undefined) {
+    if (ts.isJsxElement(current) || ts.isJsxSelfClosingElement(current)) {
+      const local = jsxLocalName(current);
+      if (local !== null && imports.get(local) === component) return true;
+    }
+    current = current.parent;
+  }
+  return false;
+}
+
 function directStructuralChildren(node, imports) {
   if (!ts.isJsxElement(node)) return { names: [], hasOpaque: false };
   const names = [];
@@ -966,8 +1081,15 @@ export function checkUiStructure(file, text) {
           attributes.has(attribute),
         );
         const children = directStructuralChildren(node, imports);
+        const insidePageShell =
+          component === "Page" && hasJsxAncestor(node, imports, "PageShell");
+        const acceptedHeaders = (
+          insidePageShell
+            ? [root.alternateHeader]
+            : [root.header, root.alternateHeader]
+        ).filter(Boolean);
         const structural =
-          children.names.includes(root.header) ||
+          acceptedHeaders.some((header) => children.names.includes(header)) ||
           children.names.includes(root.body);
         // A prop removida saiu do `shorthand`, então sozinha ela não marca o nó como forma curta:
         // ele cai no ramo explícito, que cobra header e body — uma segunda mensagem inteiramente
@@ -981,18 +1103,18 @@ export function checkUiStructure(file, text) {
           add(
             node,
             component,
-            `${component} não permite misturar propriedades de shorthand com ${root.header}/${root.body}.`,
+            `${component} não permite misturar propriedades de shorthand com ${acceptedHeaders.join("/")}/${root.body}.`,
             "ui-structure-mode",
           );
         } else if (!shorthand) {
-          const headers = children.names.filter(
-            (name) => name === root.header,
+          const headers = children.names.filter((name) =>
+            acceptedHeaders.includes(name),
           ).length;
           const bodies = children.names.filter(
             (name) => name === root.body,
           ).length;
           const unexpected = children.names.some(
-            (name) => name !== root.header && name !== root.body,
+            (name) => !acceptedHeaders.includes(name) && name !== root.body,
           );
           if (
             headers !== 1 ||
@@ -1003,7 +1125,7 @@ export function checkUiStructure(file, text) {
             add(
               node,
               component,
-              `${component} explícito exige exatamente um ${root.header} e um ${root.body} como filhos diretos.`,
+              `${component} explícito exige exatamente um ${acceptedHeaders.join(" ou ")} e um ${root.body} como filhos diretos.`,
             );
           }
         }
@@ -1375,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);
@@ -1391,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/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/0004-page-content-state-is-composed.md

@@ -4,6 +4,9 @@
 > estados. Ela foi invertida: `PageState` passa a ocultá-lo em `loading`, `error` e `empty`, e a
 > restaurá-lo em `ready`. A lista de responsabilidades abaixo já descreve o comportamento novo; o
 > adendo no fim deste arquivo registra o motivo, a alternativa descartada e o que se perde.
+>
+> **Atualização (2026-09-10).** Dentro de `PageShell`, o estado integral oculta somente
+> `PageIntro`. A barra pertence à moldura persistente e continua visível (ADR 0011).
 
 ## Contexto
 

package/docs/adr/0010-page-header-owns-page-chrome.md

@@ -4,6 +4,10 @@
 - **Data:** 2026-09-09.
 - **Complementa:** ADR 0005.
 
+> **Atualização (2026-09-10).** A ADR 0011 acrescenta `PageShell` para o caso em que shell e rota
+> conhecem partes diferentes da mesma página. A barra continua sendo a apresentação compacta do
+> cabeçalho, mas o título do conteúdo passa a `PageIntro` e as ações são coordenadas pelo Opus.
+
 ## Contexto
 
 Aplicações com sidebar passaram a montar uma barra superior separada de `PageHeader` para reunir

package/docs/adr/0011-page-shell-coordinates-persistent-page-chrome.md

@@ -0,0 +1,70 @@
+# ADR 0011 — PageShell coordena o chrome persistente da página
+
+- **Status:** aceita.
+- **Data:** 2026-09-10.
+- **Revisa:** ADR 0010.
+
+## Contexto
+
+A ADR 0010 reuniu título, navegação e ações em `PageHeader`, mas partiu do pressuposto de que uma
+única camada conhece todos esses elementos. Em aplicações com navegação persistente, o shell conhece
+o breadcrumb e a moldura enquanto a rota conhece o título, as ações e o estado do conteúdo.
+
+Sem um contrato para essa divisão, consumidores criam uma barra com `PaneHeader`, projetam ações
+manualmente e escondem partes do `PageHeader` com CSS. O resultado parece correto, mas mantém duas
+anatomias concorrentes e faz um estado integral remover também a navegação persistente do shell.
+
+## Decisão
+
+`PageShell` representa a moldura persistente de uma página dentro de um shell de aplicação. Ele
+renderiza a apresentação em barra de `PageHeader`, recebe a navegação conhecida pelo shell e oferece
+o alvo canônico para ações declaradas pela `Page` descendente.
+
+Quando uma `Page` está dentro de `PageShell`, sua forma curta transforma título e descrição em
+`PageIntro`, dentro do conteúdo. `PageActions` continua declarado pela página, mas aparece na barra.
+Na forma explícita, a página usa `PageIntro` e `PageBody`. Fora de `PageShell`, a composição anterior
+com `PageHeader` continua válida; `PageIntro` também pode ser escolhido quando o conteúdo precisa de
+uma introdução sem navegação própria. As duas regiões não são equivalentes: `PageHeader` reúne o
+cabeçalho completo, enquanto `PageIntro` dá mais presença ao título dentro do conteúdo.
+
+`PageState` oculta somente `PageIntro`. A barra do `PageShell` permanece visível porque preserva
+navegação e ações globais mesmo quando o conteúdo carrega, falha ou está vazio. Uma ação que depende
+do conteúdo deve se omitir por estado na própria rota.
+
+`PageShell` não substitui o shell completo da aplicação, não inclui sidebar e não cria navegação.
+Ele apenas coordena a barra e a área em que uma única `Page` é renderizada.
+
+## Consequências
+
+- shell e rota podem continuar conhecendo partes diferentes da página sem criar componentes locais
+  de chrome;
+- título e descrição deixam de ser mascarados por seletores globais;
+- ações de página têm um único destino oficial na barra;
+- estados integrais preservam a barra e escondem somente a introdução do conteúdo;
+- a composição anterior de `Page` permanece compatível fora de `PageShell`;
+- `PageActionsTarget` continua disponível apenas para workspaces imersivos que não usam
+  `PageShell`.
+
+## Alternativas consideradas
+
+### Passar breadcrumb a cada rota
+
+Manteria toda a anatomia dentro de `Page`, mas faria cada página receber e repassar contexto que já
+pertence ao shell. Também duplicaria essa infraestrutura em seções com navegação própria.
+
+### Tornar o portal local um padrão da aplicação
+
+Resolveria somente o GrandBrasil e deixaria o design system sem contrato para a mesma divisão de
+responsabilidade em outros consumidores.
+
+### Fazer a barra desaparecer em estados integrais
+
+Repetiria o comportamento do header embutido, mas removeria navegação persistente por causa do
+estado do conteúdo. A moldura do shell não deve oscilar com a consulta da rota.
+
+## Verificação
+
+- testes cobrem a projeção das ações, a permanência da barra e a ocultação de `PageIntro` em estados
+  integrais;
+- a documentação demonstra a composição de `PageShell`, `PageIntro` e `Page` sem CSS externo;
+- consumidores removem barras paralelas e `PageActionsTarget` ao adotar o novo contrato.

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.