@softize/opus 15.2.1 → 16.0.0

package/bin/lib/gen-runner.mjs

@@ -25,7 +25,8 @@
  *       sourceConfigDir: string,    // dirname absoluto do opus.config.ts
  *       output: string,             // pasta de saída declarada no config
  *       domains: SerializedDomain[],
- *       seeds: SerializedSeed[]
+ *       seeds: SerializedSeed[],
+ *       presentations: PresentationDefinition[]
  *     }
  *
  *     SerializedDomain:
@@ -61,92 +62,113 @@
  * stubs poderem indicar que existe lógica.
  */
 
-import path from 'node:path'
-import { pathToFileURL, fileURLToPath } from 'node:url'
+import path from "node:path";
+import { pathToFileURL, fileURLToPath } from "node:url";
 
-const __filename = fileURLToPath(import.meta.url)
-const __dirname = path.dirname(__filename)
-const PACKAGE_ROOT = path.resolve(__dirname, '..', '..')
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const PACKAGE_ROOT = path.resolve(__dirname, "..", "..");
 
 // =============================================================================
 // Entrada
 // =============================================================================
 
 async function main() {
-  const configPath = process.argv[2]
-  if (typeof configPath !== 'string' || configPath.length === 0) {
-    return emitError('Caminho do config ausente (argv[2])')
+  const configPath = process.argv[2];
+  if (typeof configPath !== "string" || configPath.length === 0) {
+    return emitError("Caminho do config ausente (argv[2])");
   }
 
-  const configAbs = path.resolve(configPath)
-  const configUrl = pathToFileURL(configAbs).href
+  const configAbs = path.resolve(configPath);
+  const configUrl = pathToFileURL(configAbs).href;
 
   // Importa opus (a partir do PACKAGE_ROOT, não do consumer) — precisamos
   // do `flattenDomain` + helpers internos pra serializar.
   const opusCoreUrl = pathToFileURL(
-    path.join(PACKAGE_ROOT, 'src', 'core', 'index.ts'),
-  ).href
-  const { flattenDomain } = await import(opusCoreUrl)
+    path.join(PACKAGE_ROOT, "src", "core", "index.ts"),
+  ).href;
+  const { flattenDomain } = await import(opusCoreUrl);
 
   const opusSeedUrl = pathToFileURL(
-    path.join(PACKAGE_ROOT, 'src', 'seed', 'index.ts'),
-  ).href
+    path.join(PACKAGE_ROOT, "src", "seed", "index.ts"),
+  ).href;
   const { checkSeedRegistry, isSeedDefinition, publicSeedDefinition } =
-    await import(opusSeedUrl)
+    await import(opusSeedUrl);
+
+  const opusPresentationUrl = pathToFileURL(
+    path.join(PACKAGE_ROOT, "src", "presentation", "index.ts"),
+  ).href;
+  const { validatePresentations } = await import(opusPresentationUrl);
 
   // Acessar logical type meta dos dicts.
   const opusSchemaUrl = pathToFileURL(
-    path.join(PACKAGE_ROOT, 'src', 'schema', 'index.ts'),
-  ).href
-  const opusSchema = await import(opusSchemaUrl)
+    path.join(PACKAGE_ROOT, "src", "schema", "index.ts"),
+  ).href;
+  const opusSchema = await import(opusSchemaUrl);
 
   // Pra serializar Zod → JSON Schema reusa o caminho que `toOpenAPISpec`
   // usa. Importação direta do npm pq é dep regular da opus.
-  const { zodToJsonSchema } = await import('zod-to-json-schema')
+  const { zodToJsonSchema } = await import("zod-to-json-schema");
 
-  const pkgUrl = pathToFileURL(path.join(PACKAGE_ROOT, 'package.json')).href
-  const pkg = await import(pkgUrl, { with: { type: 'json' } }).then(
+  const pkgUrl = pathToFileURL(path.join(PACKAGE_ROOT, "package.json")).href;
+  const pkg = await import(pkgUrl, { with: { type: "json" } }).then(
     (m) => m.default,
-  )
+  );
 
   // Import dinâmico do config do consumer.
-  const mod = await import(configUrl)
-  const cfg = mod.default ?? mod.config ?? mod
-  if (cfg === undefined || cfg === null || typeof cfg !== 'object') {
+  const mod = await import(configUrl);
+  const cfg = mod.default ?? mod.config ?? mod;
+  if (cfg === undefined || cfg === null || typeof cfg !== "object") {
     return emitError(
       `Config em ${configAbs} não exporta um objeto default ou named "config"`,
-    )
+    );
   }
 
   if (!Array.isArray(cfg.domains)) {
     return emitError(
       `Config em ${configAbs} precisa de \`domains: DomainConfig[]\` no export default`,
-    )
+    );
   }
 
-  const outputDir = typeof cfg.output === 'string' ? cfg.output : '.gen'
+  const outputDir = typeof cfg.output === "string" ? cfg.output : ".gen";
 
   const ctx = {
     flattenDomain,
     toJsonSchema: (schema) =>
-      zodToJsonSchema(schema, { target: 'openApi3', $refStrategy: 'none' }),
+      zodToJsonSchema(schema, { target: "openApi3", $refStrategy: "none" }),
     sourceConfigDir: path.dirname(configAbs),
-  }
+  };
 
-  const domains = cfg.domains.map((d) => serializeDomain(d, ctx))
+  const domains = cfg.domains.map((d) => serializeDomain(d, ctx));
+  if (cfg.presentations !== undefined && !Array.isArray(cfg.presentations)) {
+    throw new Error(
+      "config.presentations inválido — use um array de declarações registradas",
+    );
+  }
+  const actionRegistry = Object.fromEntries(
+    cfg.domains
+      .flatMap((domain) => collectDomainActions(domain))
+      .map((action) => [action.name, action]),
+  );
+  const presentations = validatePresentations(
+    cfg.presentations ?? [],
+    actionRegistry,
+  );
   if (cfg.seeds !== undefined && !Array.isArray(cfg.seeds)) {
-    throw new Error('config.seeds inválido — use um array de declarações registradas')
+    throw new Error(
+      "config.seeds inválido — use um array de declarações registradas",
+    );
   }
-  const registeredSeeds = cfg.seeds ?? []
-  const seedCheck = checkSeedRegistry(registeredSeeds)
+  const registeredSeeds = cfg.seeds ?? [];
+  const seedCheck = checkSeedRegistry(registeredSeeds);
   if (!seedCheck.ok) {
     throw new Error(
-      `config.seeds inválido — ${seedCheck.diagnostics.map((diagnostic) => diagnostic.message).join('; ')}`,
-    )
+      `config.seeds inválido — ${seedCheck.diagnostics.map((diagnostic) => diagnostic.message).join("; ")}`,
+    );
   }
   const seeds = registeredSeeds.map((seed) =>
     serializeSeed(seed, isSeedDefinition, publicSeedDefinition),
-  )
+  );
 
   const payload = {
     opusVersion: pkg.version,
@@ -154,16 +176,27 @@ async function main() {
     output: outputDir,
     domains,
     seeds,
-  }
+    presentations,
+  };
 
-  emit({ ok: true, payload })
+  emit({ ok: true, payload });
+}
+
+function collectDomainActions(domain) {
+  const actions = Array.from(iterateActions(domain.actions));
+  for (const subdomain of Array.isArray(domain.subdomains)
+    ? domain.subdomains
+    : []) {
+    actions.push(...collectDomainActions(subdomain));
+  }
+  return actions;
 }
 
 function serializeSeed(seed, isSeedDefinition, publicSeedDefinition) {
   if (!isSeedDefinition(seed)) {
-    throw new Error('config.seeds contém uma declaração inválida')
+    throw new Error("config.seeds contém uma declaração inválida");
   }
-  return publicSeedDefinition(seed)
+  return publicSeedDefinition(seed);
 }
 
 // =============================================================================
@@ -171,7 +204,7 @@ function serializeSeed(seed, isSeedDefinition, publicSeedDefinition) {
 // =============================================================================
 
 function serializeDomain(domain, ctx) {
-  const entityList = serializeEntities(domain.entities)
+  const entityList = serializeEntities(domain.entities);
   return {
     name: domain.name,
     description: nullable(domain.description),
@@ -192,7 +225,7 @@ function serializeDomain(domain, ctx) {
     subdomains: Array.isArray(domain.subdomains)
       ? domain.subdomains.map((s) => serializeDomain(s, ctx))
       : [],
-  }
+  };
 }
 
 function serializeDataProducts(source) {
@@ -220,7 +253,16 @@ function serializeDataProducts(source) {
       : [],
     entities: Array.isArray(product.entities) ? product.entities : [],
     access: {
-      contexts: Array.isArray(product.access?.contexts) ? product.access.contexts : [],
+      permissionContexts: Array.isArray(product.access?.permissionContexts)
+        ? product.access.permissionContexts
+        : Array.isArray(product.access?.contexts)
+          ? product.access.contexts
+          : [],
+      contexts: Array.isArray(product.access?.permissionContexts)
+        ? product.access.permissionContexts
+        : Array.isArray(product.access?.contexts)
+          ? product.access.contexts
+          : [],
       organizationalScopes: Array.isArray(product.access?.organizationalScopes)
         ? product.access.organizationalScopes
         : [],
@@ -234,13 +276,18 @@ function serializeDataProducts(source) {
 /** 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) {
-  if (src === undefined || src === null || typeof src !== 'object') return []
-  const out = []
+  if (src === undefined || src === null || typeof src !== "object") return [];
+  const out = [];
   for (const [key, ent] of Object.entries(src)) {
-    if (ent === null || typeof ent !== 'object' || typeof ent.fields !== 'object') continue
-    const fields = []
+    if (
+      ent === null ||
+      typeof ent !== "object" ||
+      typeof ent.fields !== "object"
+    )
+      continue;
+    const fields = [];
     for (const [fname, f] of Object.entries(ent.fields)) {
-      const col = f?.column ?? {}
+      const col = f?.column ?? {};
       fields.push({
         name: fname,
         logicalType: f?.meta?.logicalType ?? null,
@@ -248,70 +295,68 @@ function serializeEntities(src) {
         pk: col.pk === true,
         references: col.references ?? null,
         doc: col.doc ?? null,
-      })
+      });
     }
     out.push({
-      name: typeof ent.name === 'string' ? ent.name : key,
-      description: typeof ent.description === 'string' ? ent.description : null,
-      table: typeof ent.table === 'string' ? ent.table : null,
+      name: typeof ent.name === "string" ? ent.name : key,
+      description: typeof ent.description === "string" ? ent.description : null,
+      table: typeof ent.table === "string" ? ent.table : null,
       fields,
       relations: ent.relations ?? null,
-    })
+    });
   }
-  return out
+  return out;
 }
 
 function serializeDicts(dicts) {
-  if (dicts === undefined || dicts === null || typeof dicts !== 'object') {
-    return {}
+  if (dicts === undefined || dicts === null || typeof dicts !== "object") {
+    return {};
   }
-  const out = {}
+  const out = {};
   for (const [name, dict] of Object.entries(dicts)) {
-    if (dict === null || typeof dict !== 'object') continue
+    if (dict === null || typeof dict !== "object") continue;
     // DictType expõe `meta.params.entries`. Fallback: tenta `.keys()` +
     // `.metaFor(k)` caso seja shape custom.
-    const meta = dict.meta
+    const meta = dict.meta;
     if (
       meta !== undefined &&
       meta !== null &&
-      meta.logicalType === 'dict' &&
+      meta.logicalType === "dict" &&
       meta.params !== undefined
     ) {
-      const params = meta.params
-      const keys = Array.isArray(params.keys) ? params.keys : []
+      const params = meta.params;
+      const keys = Array.isArray(params.keys) ? params.keys : [];
       const entries =
         params.entries !== undefined && params.entries !== null
           ? params.entries
-          : {}
-      const values = {}
+          : {};
+      const values = {};
       for (const k of keys) {
-        values[k] = entries[k] ?? null
+        values[k] = entries[k] ?? null;
       }
       // `doc` = entendimento do vocabulário inteiro (o que esse dict representa);
       // `presentation` = papel de apresentação declarado (ADR 0003) — null quando ausente.
       out[name] = {
         keys,
         values,
-        doc: typeof params.doc === 'string' ? params.doc : null,
-        presentation: typeof params.presentation === 'string' ? params.presentation : null,
-      }
-      continue
+        doc: typeof params.doc === "string" ? params.doc : null,
+        presentation:
+          typeof params.presentation === "string" ? params.presentation : null,
+      };
+      continue;
     }
     // Fallback: dict-like com `keys()` + `metaFor()`.
-    if (
-      typeof dict.keys === 'function' &&
-      typeof dict.metaFor === 'function'
-    ) {
-      const keys = dict.keys()
-      const values = {}
-      for (const k of keys) values[k] = dict.metaFor(k)
-      out[name] = { keys, values }
-      continue
+    if (typeof dict.keys === "function" && typeof dict.metaFor === "function") {
+      const keys = dict.keys();
+      const values = {};
+      for (const k of keys) values[k] = dict.metaFor(k);
+      out[name] = { keys, values };
+      continue;
     }
     // Não-reconhecível: registra placeholder pra não silenciar.
-    out[name] = { keys: [], values: {}, unknownShape: true }
+    out[name] = { keys: [], values: {}, unknownShape: true };
   }
-  return out
+  return out;
 }
 
 function serializeAction(action, ctx) {
@@ -342,43 +387,43 @@ function serializeAction(action, ctx) {
     examples: Array.isArray(action.examples) ? action.examples : [],
     errors: Array.isArray(action.errors) ? action.errors : [],
     sourceModule: lookupSourceModule(action, ctx),
-  }
+  };
 
-  if (action.kind === 'simple' || action.kind === 'form') {
-    base.emits = Array.isArray(action.emits) ? action.emits : []
+  if (action.kind === "simple" || action.kind === "form") {
+    base.emits = Array.isArray(action.emits) ? action.emits : [];
     base.background =
       action.background !== undefined &&
       action.background !== null &&
-      action.background.enabled === true
+      action.background.enabled === true;
   }
 
-  if (action.kind === 'form') {
-    base.fields = serializeFields(action.fields)
+  if (action.kind === "form") {
+    base.fields = serializeFields(action.fields);
   }
 
-  if (action.kind === 'list') {
-    base.filters = serializeFilters(action.filters)
-    base.sort = action.sort ?? null
-    base.paginate = action.paginate ?? null
-    base.text = action.text ?? null
-    base.periods = Array.isArray(action.periods) ? action.periods : []
+  if (action.kind === "list") {
+    base.filters = serializeFilters(action.filters);
+    base.sort = action.sort ?? null;
+    base.paginate = action.paginate ?? null;
+    base.text = action.text ?? null;
+    base.periods = Array.isArray(action.periods) ? action.periods : [];
   }
 
-  if (action.kind === 'view') {
-    base.projection = Array.isArray(action.projection) ? action.projection : []
-    base.expand = action.expand ?? null
+  if (action.kind === "view") {
+    base.projection = Array.isArray(action.projection) ? action.projection : [];
+    base.expand = action.expand ?? null;
   }
 
-  return base
+  return base;
 }
 
 function serializeFields(fields) {
-  if (fields === undefined || fields === null || typeof fields !== 'object') {
-    return {}
+  if (fields === undefined || fields === null || typeof fields !== "object") {
+    return {};
   }
-  const out = {}
+  const out = {};
   for (const [name, spec] of Object.entries(fields)) {
-    if (spec === null || typeof spec !== 'object') continue
+    if (spec === null || typeof spec !== "object") continue;
     out[name] = {
       label: spec.label ?? null,
       placeholder: spec.placeholder ?? null,
@@ -390,21 +435,25 @@ function serializeFields(fields) {
       order: spec.order ?? null,
       widget: spec.widget ?? null,
       options: spec.options ?? null,
-      hasShowWhen: typeof spec.showWhen === 'function',
-      hasRequireWhen: typeof spec.requireWhen === 'function',
+      hasShowWhen: typeof spec.showWhen === "function",
+      hasRequireWhen: typeof spec.requireWhen === "function",
       aiDescription: spec.aiDescription ?? null,
-    }
+    };
   }
-  return out
+  return out;
 }
 
 function serializeFilters(filters) {
-  if (filters === undefined || filters === null || typeof filters !== 'object') {
-    return {}
+  if (
+    filters === undefined ||
+    filters === null ||
+    typeof filters !== "object"
+  ) {
+    return {};
   }
-  const out = {}
+  const out = {};
   for (const [name, spec] of Object.entries(filters)) {
-    if (spec === null || typeof spec !== 'object') continue
+    if (spec === null || typeof spec !== "object") continue;
     out[name] = {
       label: spec.label ?? null,
       placeholder: spec.placeholder ?? null,
@@ -417,9 +466,9 @@ function serializeFilters(filters) {
       depends: spec.depends ?? null,
       options: spec.options ?? null,
       aiDescription: spec.aiDescription ?? null,
-    }
+    };
   }
-  return out
+  return out;
 }
 
 function serializeReaction(reaction) {
@@ -428,13 +477,13 @@ function serializeReaction(reaction) {
     on: reaction.on,
     description: nullable(reaction.description),
     tags: Array.isArray(reaction.tags) ? reaction.tags : [],
-    handler: '<function>',
+    handler: "<function>",
     retry: reaction.retry ?? null,
     timeout: reaction.timeout ?? null,
     concurrency: reaction.concurrency ?? null,
-    hasDedup: typeof reaction.dedup === 'function',
-    hasAuthorize: typeof reaction.authorize === 'function',
-  }
+    hasDedup: typeof reaction.dedup === "function",
+    hasAuthorize: typeof reaction.authorize === "function",
+  };
 }
 
 function serializeSchedule(sched) {
@@ -448,8 +497,8 @@ function serializeSchedule(sched) {
     description: nullable(sched.description),
     tags: Array.isArray(sched.tags) ? sched.tags : [],
     input:
-      typeof sched.input === 'function' ? '<function>' : (sched.input ?? null),
-  }
+      typeof sched.input === "function" ? "<function>" : (sched.input ?? null),
+  };
 }
 
 // =============================================================================
@@ -457,16 +506,16 @@ function serializeSchedule(sched) {
 // =============================================================================
 
 function* iterateActions(actions) {
-  if (actions === undefined) return
+  if (actions === undefined) return;
   if (Array.isArray(actions)) {
-    for (const a of actions) yield a
-    return
+    for (const a of actions) yield a;
+    return;
   }
   for (const value of Object.values(actions)) {
     if (Array.isArray(value)) {
-      for (const a of value) yield a
+      for (const a of value) yield a;
     } else {
-      yield value
+      yield value;
     }
   }
 }
@@ -474,36 +523,36 @@ function* iterateActions(actions) {
 function derivePermission(action) {
   // Projeção FIEL do `requires`: lista sai lista (semântica ANY) — projetar só a
   // 1ª string faria a spec mentir por omissão pra quem lê o manifest.
-  const req = action.requires
-  if (typeof req === 'string') return req
+  const req = action.requires;
+  if (typeof req === "string") return req;
   if (Array.isArray(req)) {
-    const strs = req.filter((r) => typeof r === 'string')
-    return strs.length > 0 ? strs : null
+    const strs = req.filter((r) => typeof r === "string");
+    return strs.length > 0 ? strs : null;
   }
-  return null
+  return null;
 }
 
 function serializeAuthorize(authorize) {
-  if (authorize === undefined || authorize === null) return null
+  if (authorize === undefined || authorize === null) return null;
   // DSL: pode chegar como string em frameworks (versão futura). Hoje é fn.
-  if (typeof authorize === 'string') return authorize
-  if (typeof authorize === 'function') return '<function>'
-  return null
+  if (typeof authorize === "string") return authorize;
+  if (typeof authorize === "function") return "<function>";
+  return null;
 }
 
 function serializeInvalidates(inv) {
-  if (inv === undefined || inv === null) return null
-  if (Array.isArray(inv)) return inv
-  if (typeof inv === 'function') return '<function>'
-  return null
+  if (inv === undefined || inv === null) return null;
+  if (Array.isArray(inv)) return inv;
+  if (typeof inv === "function") return "<function>";
+  return null;
 }
 
 function safeToJsonSchema(schema, ctx) {
-  if (schema === undefined || schema === null) return null
+  if (schema === undefined || schema === null) return null;
   try {
-    return ctx.toJsonSchema(schema)
+    return ctx.toJsonSchema(schema);
   } catch (err) {
-    return { __unserializable: true, reason: err.message }
+    return { __unserializable: true, reason: err.message };
   }
 }
 
@@ -511,13 +560,13 @@ function lookupSourceModule(_action, _ctx) {
   // Não há mecanismo confiável pra extrair o source module a partir do
   // ActionDef em runtime (ESM não expõe). Reservamos o campo pra futura
   // integração com `import.meta.url` no defineAction.
-  return null
+  return null;
 }
 
 function nullable(value) {
-  if (value === undefined || value === null) return null
-  if (typeof value === 'string' && value.length === 0) return null
-  return value
+  if (value === undefined || value === null) return null;
+  if (typeof value === "string" && value.length === 0) return null;
+  return value;
 }
 
 // =============================================================================
@@ -525,14 +574,14 @@ function nullable(value) {
 // =============================================================================
 
 function emit(payload) {
-  process.stdout.write(JSON.stringify(payload) + '\n')
+  process.stdout.write(JSON.stringify(payload) + "\n");
 }
 
 function emitError(message) {
-  emit({ ok: false, error: message })
-  process.exit(1)
+  emit({ ok: false, error: message });
+  process.exit(1);
 }
 
 main().catch((err) => {
-  emitError(`runner crash: ${err.stack ?? err.message ?? String(err)}`)
-})
+  emitError(`runner crash: ${err.stack ?? err.message ?? String(err)}`);
+});

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

@@ -1,12 +1,11 @@
 # ADR 0010 — PageHeader também representa o chrome compacto da página
 
-- **Status:** aceita.
+- **Status:** substituída pela ADR 0011.
 - **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.
+> **Atualização (2026-09-11).** A ADR 0011 torna `PageShell` o único componente responsável pela
+> barra persistente. `PageHeader` volta a ter uma única apresentação dentro da página.
 
 ## Contexto
 

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

@@ -17,8 +17,9 @@ anatomias concorrentes e faz um estado integral remover também a navegação pe
 ## 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.
+renderiza a barra, recebe a navegação conhecida pelo shell e oferece o alvo canônico para ações
+declaradas pela `Page` descendente. Essa barra existe somente por `PageShell`; `PageHeader` não
+possui variante visual para reproduzi-la dentro da página.
 
 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.
@@ -41,7 +42,8 @@ Ele apenas coordena a barra e a área em que uma única `Page` é renderizada.
 - 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`;
+- a composição de `Page` com `PageHeader` permanece disponível fora de `PageShell`, sem uma segunda
+  forma de produzir a barra;
 - `PageActionsTarget` continua disponível apenas para workspaces imersivos que não usam
   `PageShell`.
 

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

@@ -27,10 +27,12 @@ descritivo e Actions de interface. Produtos ativos podem ser descontinuados com
 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
+A autorização continua sendo responsabilidade da Action. `access.permissionContexts` 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.
+incompleta abra dados. O alias histórico `access.contexts` permanece aceito como entrada e
+projetado no manifest durante a série 15.x por compatibilidade. Novos consumidores usam o nome
+qualificado; o alias será removido somente numa versão major.
 
 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