@oondemand/create-central-oon 0.7.3 → 0.7.6

package/docs/PDF_RENDERING.md

@@ -26,13 +26,12 @@ const {
   capabilities,
   defineRoutes,
   GenericError,
-  requirePermission,
 } = require("@oondemand/oon-core-back");
 
 defineRoutes("/pdf", (router) => {
   router.private.post(
     "/render",
-    requirePermission("pdf.render"),
+    { permission: "pdf.render" },
     async (req, res) => {
       if (typeof req.body?.html !== "string" || !req.body.html.trim()) {
         throw new GenericError("Informe o HTML.", {
@@ -55,7 +54,7 @@ defineRoutes("/pdf", (router) => {
           },
           {
             ...req.accessContext,
-            correlationId: req.id,
+            correlationId: req.correlationId,
             environment: process.env.APP_ENVIRONMENT,
             signal: controller.signal,
           },

package/docs/PUBLIC_CONTRACTS.md

@@ -0,0 +1,124 @@
+# Contratos públicos para a primeira jornada
+
+Piso verificado: OonCore 0.7.4. Imports backend vêm de `@oondemand/oon-core-back`; frontend de `@oondemand/oon-core-front` e seus subpaths públicos. [Índice](TASK_INDEX.md) e [API completa](BACKEND_API.md).
+
+## Bootstrap e prefixos
+
+- `npm run dev` na raiz usa o orquestrador oficial; `npm start --prefix backend` usa o CLI com o diretório do backend.
+- No bootstrap programático, `await start({ cwd: caminhoAbsolutoDoBackend, listen: false })` devolve `{ app }`; com escuta, devolve `{ app, server }`. `createApp()` monta o Express a partir do registro existente, mas não carrega o domínio nem conecta o banco sozinho.
+- `cwd` determina `central.config.js`, `central.domain.json`, `central.process.json` e `src/`. O App manifest é descoberto no backend ou em seu diretório pai.
+- São autocarregados recursivamente arquivos `.js`/`.cjs` de `src/models`, `validations`, `triggers`, `routes`, `pipelines`, `documents` e `hooks`. Serviços e assets entram pelos imports dessas extensões. Não é preciso exportar uma função de registro: execute `defineRoutes` no módulo carregado.
+- O bootstrap carrega domínio/processo antes dos módulos JS. Models usadas em um process manifest devem existir no domain manifest. Não duplique sua definição em JS.
+
+| Camada | Exemplo da mesma operação |
+|---|---|
+| Registro no backend | `defineRoutes("/demo", ...)` + `router.private.post("/saudacao", options, handler)` |
+| Backend direto | `POST /demo/saudacao` |
+| URL pública / proxy Vite | `POST /api/demo/saudacao` |
+| `useOonApi` com baseUrl `/api` | `http.post("/demo/saudacao", body)` |
+
+O proxy existente remove `/api`; não registre esse prefixo novamente nem o duplique na chamada do cliente. Preserve a configuração fornecida pelo scaffold/delivery. Para diferenças entre checkout e imagem, consulte [APP_PACKAGING.md](APP_PACKAGING.md).
+
+## Rotas privadas
+
+```js
+const { defineRoutes } = require("@oondemand/oon-core-back");
+
+defineRoutes("/integracao", (router) => {
+  router.private.put("/credencial", {
+    permission: "integracao.config.write",
+    sensitiveBody: true,
+  }, async (req, res) => {
+    // Neste exemplo de assinatura, nenhuma credencial é persistida.
+    res.status(501).json({ message: "Implemente a persistência cifrada no App." });
+  });
+});
+```
+
+Assinatura: `router.private[METHOD](path, options, handler)`, com `get`, `post`, `put`, `patch`, `delete`. Há forma curta `(path, handler)`, porém ela não declara uma permissão de negócio; prefira opções explícitas.
+
+- `permission: "dominio.acao"` é a forma recomendada. `permissions: ["a.read", "b.read"]` aceita **qualquer uma** das permissões; não significa exigir todas. Evite declarar ambos.
+- `roles` é compatibilidade legada, não uma substituição da política RBAC declarada.
+- `audit` configura auditoria de mutação quando necessária; não coloque dados secretos nela.
+- **Não** passe `requirePermission(...)` como segundo argumento e o handler como terceiro. Antes da validação introduzida nesta entrega, uma função nessa posição era interpretada como o próprio handler, descartando o terceiro argumento. Na release __OONCORE_VERSION__, essa assinatura lança OON_ROUTE_REGISTRATION_INVALID no registro. O wrapper não é a assinatura variádica do Express. `requirePermission` é um middleware público para composições compatíveis, não uma opção de `router.private`.
+- `router.public` não deve ser usado para evitar autenticação de uma operação privada.
+
+Declare a permissão em `central.app.json` → `rbac.permissions` (array de strings) e conceda-a em `rbac.roles[].permissions`. Preserve os demais campos/papéis. O admin do scaffold já tem `permissions: ["*"]`; isso não dispensa a declaração de permissões nem o contexto autorizado no backend. Operações com dados próprios devem usar `req.accessContext` e os helpers de escopo documentados em [BACKEND_API.md](BACKEND_API.md).
+
+## Corpo sensível e erros
+
+`sensitiveBody: true` em `post`, `put`, `patch` ou `delete` privado omite entrada e resposta no `requestLog` para o método/caminho, inclusive em erro. Não cifra banco, não mascara seletivamente campos, não cobre automaticamente CRUD, GET, console, logs de integração, auditoria ou payload de exceções. Credenciais pertencem a um armazenamento protegido do App ou a um contrato público disponível na release; nunca ao frontend/manifesto/URL.
+
+Lance `new GenericError(mensagemSegura, { statusCode, code, details })`. O envelope de domínio com `code` é:
+
+```json
+{
+  "message": "Informe um nome de até 80 caracteres.",
+  "error": {
+    "code": "DEMO_NAME_INVALID",
+    "message": "Informe um nome de até 80 caracteres.",
+    "requestId": "correlacao-quando-disponivel"
+  }
+}
+```
+
+`details` e `requestId` são opcionais. O Core não sanitiza arbitrariamente o conteúdo que o App coloca em `message`/`details`; normalize erros externos antes de lançá-los. Respostas legadas e recusas de auth podem conter somente `message`; 404 do proxy/Express pode ser HTML. Não trate erro de rede/404 como sucesso vazio. Veja [ERRORS.md](ERRORS.md).
+
+## Primeira jornada executável
+
+No App gerado, adicione `"demo.execute"` a `rbac.permissions`. Mantenha o admin existente. Crie `backend/src/routes/demo.js`:
+
+```js
+const { defineRoutes, GenericError } = require("@oondemand/oon-core-back");
+
+defineRoutes("/demo", (router) => {
+  router.private.post("/saudacao", { permission: "demo.execute" }, async (req, res) => {
+    const nome = typeof req.body?.nome === "string" ? req.body.nome.trim() : "";
+    if (!nome || nome.length > 80) {
+      throw new GenericError("Informe um nome de até 80 caracteres.", {
+        statusCode: 422, code: "DEMO_NAME_INVALID",
+      });
+    }
+    res.json({ message: `Olá, ${nome}!` });
+  });
+});
+```
+
+Substitua `frontend/src/pages/HomePage.tsx`. A rota `/` e o item Início já são registrados pelo scaffold:
+
+```tsx
+import { useState, type FormEvent } from "react";
+import { useOonApi } from "@oondemand/oon-core-front";
+
+export function HomePage() {
+  const { http } = useOonApi();
+  const [nome, setNome] = useState("");
+  const [resultado, setResultado] = useState("");
+  const [busy, setBusy] = useState(false);
+  async function submit(event: FormEvent) {
+    event.preventDefault();
+    setBusy(true);
+    try {
+      const response = await http.post("/demo/saudacao", { nome });
+      setResultado(response.data.message);
+    } catch (error: unknown) {
+      const response = (error as { response?: { status?: number; data?: {
+        message?: string; error?: { code?: string; message?: string };
+      } } }).response;
+      setResultado(response?.data?.error?.message || response?.data?.message
+        || `Não foi possível executar a ação (HTTP ${response?.status ?? "indisponível"}).`);
+    } finally { setBusy(false); }
+  }
+  return <form onSubmit={submit}>
+    <h1>Primeira jornada</h1>
+    <label>Nome <input value={nome} onChange={event => setNome(event.target.value)} /></label>
+    <button type="submit" disabled={busy}>Executar</button>
+    <p role="status">{resultado}</p>
+  </form>;
+}
+```
+
+Reinicie `npm run dev` após incluir o módulo, abra Início com admin e execute com nome válido e vazio (422). Selecione viewer, sem `demo.execute`, e confirme a recusa (403). O cliente do Core cuida de sessão e CSRF; não crie token fixo. A saudação é uma ação sem persistência; para um cadastro, siga [TASK_EXAMPLES.md](TASK_EXAMPLES.md). Estes blocos são exemplos documentais copiáveis, não uma suíte integrada de homologação do SDK.
+
+
+A release __OONCORE_VERSION__ também diagnostica a raiz do App passada como cwd com OON_BACKEND_CWD_INVALID. Caminhos relativos são resolvidos antes do autoload. Use `create-central-oon example` em uma base limpa para instalar a jornada integrada descrita em [EXECUTABLE_EXAMPLE.md](EXECUTABLE_EXAMPLE.md).

package/docs/RBAC_SECURITY.md

@@ -46,7 +46,7 @@ Resposta:
 }
 ```
 
-Use esse endpoint para montar seletores e validar grants por App. Não mantenha códigos de perfil paralelos no frontend ou no Control Plane. O consumidor deve validar versão e App, bloquear redirects e destinos de rede privados, revalidar o perfil no backend e tratar catálogo inválido como indisponível. O endpoint usa cache público de cinco minutos e nunca expõe a lista de permissões; a autorização efetiva continua no App.
+Use esse endpoint para montar seletores e validar grants por App. Não mantenha códigos de perfil paralelos no frontend ou no Control Plane. O consumidor deve validar versão e App, bloquear redirects e destinos de rede privados, revalidar o perfil no backend e tratar catálogo inválido como indisponível. O endpoint usa cache público de cinco minutos. Desde 0.7.1, pode incluir `commercialPermissions` com permissões funcionais declaradas; não publica wildcards literais nem namespaces operacionais reservados. Esse catálogo não concede autorização; a decisão efetiva continua no App.
 
 ## Checklist de segurança para Agents
 

package/docs/ROUTES_HOOKS_WORKERS.md

@@ -1,11 +1,22 @@
-# Rotas, hooks, triggers e workers
+# Rotas, hooks, triggers e execução de processos
 
-- `defineRoutes(basePath, router)`: registra rota específica do domínio. Proteja com auth já montada, `requirePermission`, validação e `req.accessContext`.
-- `defineValidation(model, fn)`: valida o estado consolidado antes de persistir.
-- `defineTrigger(model, fn)`: efeito de domínio rastreável associado à mutação.
-- Process manifest: transições, bindings, invariantes, recálculos e jobs transacionais.
-- Integration runtime: outbox/inbox, retry, lock, idempotência, histórico e webhook.
+Para assinatura de `defineRoutes`, opções de `router.private`, bootstrap, prefixos, permissões, erros e `sensitiveBody`, use [PUBLIC_CONTRACTS.md](PUBLIC_CONTRACTS.md).
 
-Não crie processo web paralelo, registry local, timer genérico ou worker que replique o Core. Jobs devem ser idempotentes, limitar retry, sanitizar payload/erro e encerrar com o lifecycle do processo.
+## Existente e público
 
-No runtime local, workers e filas podem operar contra Mongo local, mas operações que exigem identidade da plataforma devem retornar `LOCAL_OPERATION_NOT_SUPPORTED`.
+- `defineValidation(model, fn)`: valida estado consolidado antes de persistir.
+- `defineTrigger(model, { before, after })`: registra efeitos de domínio associados à mutação. Não trate hooks como entrega exatamente uma vez de efeitos externos.
+- `central.process.json`: transições, bindings, invariantes e recálculos suportados. [Contrato completo](BACKEND_PROCESS_MANIFEST.md).
+- `capabilities.transactionalEmail`: envio e acompanhamento de e-mail, com fila própria. [Contrato completo](TRANSACTIONAL_EMAIL.md).
+
+## Interno e específico
+
+Jobs de recálculo do processo e workers de e-mail atendem esses recursos; não são uma fila genérica durável para integração externa. `drainProcessJobs` não define enqueue/claim/retry de tarefas arbitrárias. Stores, transports e registries internos não são pontos de extensão de Apps.
+
+## Integração no App e proposta futura
+
+Não há API pública genérica de “integration runtime” para outbox/inbox, locks, retry ou webhooks nesta release. Chamadas externas, mapeamentos, regras fiscais, estado de operação e recuperação de negócio ficam no App por rotas/serviços documentados. [Exemplo de consulta](TASK_EXAMPLES.md#integração).
+
+Quando a jornada precisar de execução assíncrona durável, explicite persistência, idempotência, concorrência, retry limitado, diagnóstico sanitizado e lifecycle no App, ou acompanhe uma nova Capacidade em escopo separado. Não invente APIs do Core, não transforme um timer em garantia de durabilidade e não bloqueie funções independentes à espera da nova Capacidade.
+
+O runtime local não fornece identidade operacional da Plataforma. Operações que a exigem continuam falhando fechado conforme [LOCAL_SECURITY_BOUNDARY.md](LOCAL_SECURITY_BOUNDARY.md).

package/docs/SECRETS.md

@@ -0,0 +1,54 @@
+# core.secrets V1
+
+Contrato público a partir da release 0.7.6. Backend: `const { capabilities } = require("@oondemand/oon-core-back")`. Exclusivo para `single_tenant` + `dedicated`. Nenhum endpoint/CRUD automático expõe a coleção técnica. Adoção é opt-in; não migra e-mail nem Apps existentes.
+
+```json
+{
+  "capabilities": ["core.secrets"],
+  "capabilitySettings": { "core.secrets": { "enabled": true } }
+}
+```
+
+Mescle a declaração no manifesto existente. Nunca coloque valores ou chave em manifesto, frontend, repositório ou imagem. O Publisher transmite somente a declaração. Core e executor precisam da release com V1; versão anterior deve recusar a publicação opt-in.
+
+```js
+const options = { name: "omie", context: req.accessContext, correlationId: crypto.randomUUID() };
+await capabilities.secrets.put({ ...options, value: { appKey, appSecret } });
+const state = await capabilities.secrets.status(options);
+await capabilities.secrets.use(options, async credential => {
+  // Serviço do App controla URL, timeout, redirects e sanitização do retorno.
+  await omie.call(credential);
+});
+await capabilities.secrets.remove(options);
+```
+
+`context` é o contexto autorizado do Core; nunca copie identidade do body/header. Rotas do App exigem autenticação, permissão de negócio e `sensitiveBody: true`. A V1 verifica App, tenant e usuário; a autorização da operação é da rota. Não oferece execução anônima/sistema nem contorno de RBAC.
+
+- Nome: `[a-z][a-z0-9._-]{0,63}`, definido pelo backend. Dois nomes são independentes.
+- Valor: objeto JSON não vazio, até 16 KiB serializado. Substituição atômica do objeto inteiro; não há merge parcial, histórico ou compare-and-swap. Última gravação concluída prevalece.
+- `put` retorna apenas `{state:"available"}`; valor incompatível exige `replace: true` explícito. Chave indisponível impede gravação inclusive com replace.
+- `status` retorna `absent`, `available` ou `reentry_required`. `reason:key_unavailable`/`action:restore_provisioning` exige intervenção antes do recadastro; `incompatible_or_unreadable`/`replace` permite substituição autorizada. Erro de banco retorna erro sanitizado, nunca “ausente”.
+- `use(options, callback)` aguarda o callback e **descarta seu retorno**. Erros do callback tornam-se `SECRETS_USE_FAILED`, sem mensagem/cause externa. Código do App deve decidir quais resultados sanitizados expor.
+- `remove` é idempotente e não precisa decifrar o valor.
+- Correlação opcional: 1–128 caracteres alfanuméricos, `:`, `_` ou `-`; gere no backend. Auditoria técnica registra tentativa de operação, ator, escopo, nome, correlação e instante, sem valor/envelope/chave. Não é confirmação transacional do efeito.
+
+AES-256-GCM, chave aleatória de 32 bytes, IV novo de 12 bytes por gravação. Envelope v1 autenticado com AAD que inclui App, identidade canônica do runtime dedicado (appId + namespace), ambiente, tenant e nome. Uma chave por namespace/ambiente. As coleções `oon_secrets` e `oon_secret_audit` são técnicas, não registradas em CRUD/metadata/export.
+
+`use` não é sandbox: código consumidor pode copiar/logar strings ou exfiltrá-las. Nunca registre payload, headers, erros de SDK externo ou resposta remota sem sanitização. Limpeza dos buffers não garante apagar todas as cópias de strings do heap. A criptografia protege valores em repouso separados da chave; um processo backend comprometido pode acessar os valores.
+
+## Provisionamento e recadastro
+
+O helper de delivery cria Secret imutável `oon-core-secrets` por `create` atômico; concorrentes releem o vencedor. Erro de leitura não gera chave. A chave não passa em argumentos CLI, logs, contexto de publicação ou evidência. `secretKeyRef` monta somente OON_SECRETS_KEY do ambiente alvo, opcional para permitir que funções independentes iniciem mesmo se a chave desaparecer. Campos extras de um Secret restaurado não são injetados. Identidade/tenant não secretos permanecem no runtime base; nenhuma operação de segredo ignora a falta da chave. Um Secret marcador imutável `oon-core-secrets-initialized` guarda apenas o vínculo público e impede recriação silenciosa se a chave desaparecer. Não há serviço de cofre. O RBAC do Publisher recebe somente leitura nominal dos dois Secrets; criação de Secrets já existe.
+
+Republicação, reinício e réplica reutilizam Secret/coleção. Promoção transporta declaração/imagem; provisiona chave independente no destino, sem copiar dados ou chave da origem.
+
+1. Para valor incompatível com chave íntegra: usuário autorizado informa o objeto completo e confirma `replace: true`.
+2. Se a chave estiver ausente: operador restaura o Secret correspondente, sem imprimir/exportar sua chave para diagnósticos. O provisionamento normal recusa perda ou corrupção.
+3. Sem chave recuperável: operador interrompe o runtime alvo, confirma identidade/ambiente e aceita a perda dos valores antigos. Remove **somente** o Secret e marcador daquele ambiente por procedimento operacional autorizado e reexecuta provisionamento. Depois republica/reinicia todas as réplicas e solicita recadastro explícito. Não há endpoint do App para trocar chave.
+4. Exclusão do namespace/ambiente ou restauração de banco sem a chave correspondente pode exigir recadastro. Não há recuperação, rotação ou migração transparente nesta V1.
+
+## Prova gerada e desenvolvimento local
+
+`create-central-oon sample --no-install` seguido de `create-central-oon example` instala `/segredos`, menu, permissão `segredos.manage` e rotas públicas do SDK. O exemplo opt-in já declara a capacidade. Configure no **ambiente do backend**, persistindo de forma segura entre reinícios: `OON_SECRETS_KEY` (32 bytes base64 padrão), `OON_SECRETS_INSTANCE=local:sample`, `OON_SECRETS_TENANT=local:tenant`, `APP_ENVIRONMENT=desenvolvimento`. Nunca use a chave local na Plataforma.
+
+`INTEGRACAO_URL` é endpoint HTTPS controlado pelo operador, que receberá POST do objeto de prova; não é implementação fiscal/Omie. Sem chave, outras páginas continuam operacionais. Use credenciais sintéticas no teste. A suíte HTTP gera o App, usa Core/Mongo reais e HTTPS de teste, cobre autorização, dois nomes, cifra, adulteração, recadastro, concorrência, erros/logs e reinício empacotado. Isso não substitui release npm nem homologação Dev pública.

package/docs/TASK_EXAMPLES.md

@@ -0,0 +1,134 @@
+# Exemplos por tarefa
+
+Piso verificado: 0.7.4. Execute no App gerado seguindo [o roteiro](OON_APP_AGENT_GUIDE.md). Estes exemplos são blocos copiáveis para as tarefas; a suíte integrada e o exemplo instalável estão descritos em [EXECUTABLE_EXAMPLE.md](EXECUTABLE_EXAMPLE.md). Preserve o manifesto existente e acrescente apenas os campos indicados.
+
+## Cadastro e lista
+
+Adicione `pessoas.read` e `pessoas.write` a `rbac.permissions` de `central.app.json`; use admin na POC. Crie `backend/src/models/Pessoa.js`:
+
+```js
+const { defineModel, fields } = require("@oondemand/oon-core-back");
+
+defineModel({
+  name: "Pessoa", singular: "pessoa", basePath: "/pessoas", scope: "tenant",
+  schema: { nome: fields.string({ required: true, label: "Nome" }) },
+  crud: { enabled: true, permissions: { read: "pessoas.read", write: "pessoas.write" } },
+});
+```
+
+Substitua `frontend/src/pages/HomePage.tsx`; a rota e o menu Início existentes tornam o cadastro acessível:
+
+```tsx
+import { CoreCollection } from "@oondemand/oon-core-front";
+
+export function HomePage() {
+  return <CoreCollection model="Pessoa" label="Pessoas" endpoint="/pessoas" />;
+}
+```
+
+Reinicie `npm run dev`. Em Início, crie uma pessoa, consulte a lista e recarregue para confirmar persistência. Nome ausente deve ser recusado; viewer sem as permissões não pode ler/gravar. O formulário é derivado da metadata. Não use esse CRUD para armazenar segredos: `sensitiveBody` de rota customizada não é aplicado aqui.
+
+## Esteira
+
+Restrito ao App `single_tenant` com banco dedicado gerado pelo scaffold. O domain manifest desta versão não propaga `scope`/`tenancy` para a model: não use este exemplo como isolamento de linhas multi-tenant. Registre essa lacuna se precisar combinar processo declarativo com esse escopo; não invente campos de manifesto. Para cadastro com isolamento explícito, use `defineModel({ scope: "tenant", ... })` do exemplo anterior.
+
+Este exemplo independente usa `backend/central.domain.json` (não crie outra model `Ticket` em JS):
+
+```json
+{
+  "schemaVersion": 1, "name": "Exemplo de tickets",
+  "models": [{
+    "name": "Ticket", "singular": "ticket", "basePath": "/tickets",
+    "crud": { "enabled": true, "permissions": { "read": "tickets.read", "write": "tickets.write" } },
+    "fields": {
+      "titulo": { "kind": "string", "required": true },
+      "etapa": { "kind": "enum", "values": ["Aberto", "Concluido"], "default": "Aberto" }
+    }
+  }]
+}
+```
+
+Crie `backend/central.process.json`:
+
+```json
+{
+  "schemaVersion": 1,
+  "models": {
+    "Ticket": { "workflow": {
+      "stageField": "etapa", "initialStages": ["Aberto"], "defaultStage": "Aberto",
+      "transitions": [{ "from": "Aberto", "to": "Concluido" }]
+    } }
+  }
+}
+```
+
+Declare `tickets.read` e `tickets.write` em `rbac.permissions` e use admin. Substitua `frontend/src/pages/HomePage.tsx`:
+
+```tsx
+import { CorePipeline } from "@oondemand/oon-core-front";
+
+export function HomePage() {
+  return <CorePipeline model="Ticket" label="Tickets" endpoint="/tickets"
+    titleField="titulo" stageField="etapa" create={{ enabled: true, defaultStage: "Aberto" }}
+    defaultActions={{ workStatus: false }}
+    stages={[{ id: "Aberto", label: "Aberto" }, { id: "Concluido", label: "Concluído" }]} />;
+}
+```
+
+Reinicie, crie um ticket em Aberto e mova para Concluído; o retorno para Aberto deve ser recusado pelo backend. A esteira não executa chamadas externas automaticamente. Consulte [BACKEND_PROCESS_MANIFEST.md](BACKEND_PROCESS_MANIFEST.md) para bindings/invariantes.
+
+## Integração
+
+Não existe contrato genérico de “integration runtime” nesta release. Uma consulta externa pode usar uma rota privada e um serviço no App. Para executar o exemplo, configure `INTEGRACAO_URL` (endpoint HTTPS controlado por você) e `INTEGRACAO_TOKEN` no ambiente do backend; nunca versione o token. Ele usa Bearer, portanto adapte o mapeamento ao contrato do sistema externo.
+
+Crie `backend/src/routes/integracao.js` e declare `integracao.test` em `rbac.permissions`:
+
+```js
+const { defineRoutes, GenericError } = require("@oondemand/oon-core-back");
+
+defineRoutes("/integracao", (router) => {
+  router.private.post("/testar", { permission: "integracao.test", sensitiveBody: true }, async (req, res) => {
+    const url = process.env.INTEGRACAO_URL;
+    const token = process.env.INTEGRACAO_TOKEN;
+    if (!url || !token) throw new GenericError("Configure a integração.", {
+      statusCode: 409, code: "INTEGRATION_NOT_CONFIGURED",
+    });
+    let target;
+    try { target = new URL(url); } catch { /* tratado abaixo */ }
+    if (!target || target.protocol !== "https:" || target.username || target.password) {
+      throw new GenericError("Configure um endpoint HTTPS sem credenciais na URL.", {
+        statusCode: 422, code: "INTEGRATION_URL_INVALID",
+      });
+    }
+    let response;
+    try {
+      response = await fetch(target, {
+        headers: { Authorization: `Bearer ${token}` },
+        signal: AbortSignal.timeout(10000), redirect: "error",
+      });
+    } catch {
+      throw new GenericError("O serviço externo não respondeu no prazo ou está indisponível.", {
+        statusCode: 502, code: "INTEGRATION_TRANSPORT_ERROR",
+      });
+    }
+    await response.body?.cancel();
+    if (!response.ok) throw new GenericError("O serviço externo recusou a consulta.", {
+      statusCode: 502, code: "INTEGRATION_REMOTE_REJECTED", details: { remoteStatus: response.status },
+    });
+    res.json({ message: "Consulta externa concluída." });
+  });
+});
+```
+
+Para uma página utilizável, reutilize o `HomePage` de [PUBLIC_CONTRACTS.md](PUBLIC_CONTRACTS.md) e troque a chamada por `http.post("/integracao/testar", {})`; o input nome pode ser removido. Reinicie e teste sucesso, configuração ausente e rejeição externa. O exemplo apenas consulta: não cadastra credenciais, não comprova uma operação fiscal nem oferece retry/persistência de jobs. Credenciais recebidas pela UI exigem armazenamento cifrado próprio e respostas sanitizadas.
+
+## Diagnóstico
+
+Após publicar, consulte (substitua o host pelo endereço real de Dev):
+
+```bash
+curl --fail-with-body https://SEU-APP-DEV/api/health/ready
+curl --fail-with-body https://SEU-APP-DEV/api/health/version
+```
+
+Para uma ação privada, reproduza pela página com `useOonApi` autenticado e registre método, caminho, status, código e correlação sem segredos. Confira se `/api` foi acrescentado apenas na URL pública, se o módulo está em `backend/src/routes` e se o commit é o publicado. HTML 404 indica investigar rota/proxy/empacotamento; não é prova de rejeição da API externa. Readiness não prova execução do handler de domínio.

package/docs/TASK_INDEX.md

@@ -0,0 +1,36 @@
+# Índice por intenção
+
+Documentação distribuída da release **__OONCORE_VERSION__**. Escolha a linha da tarefa; não é necessário ler todos os guias.
+
+**Versão mínima:** 0.7.4 é o piso verificado dos exemplos deste roteiro, não uma alegação de que cada API surgiu nessa versão. PDF e e-mail têm contrato dedicado desde 0.6.0. Use versões coordenadas dos três pacotes e não presuma compatibilidade com versões anteriores ao piso indicado.
+
+| Quero… | API/export público | Mínima do roteiro | Exemplo executável / referência completa | Limite principal |
+|---|---|---|---|---|
+| Cadastrar e listar | back: `defineModel`, `fields`; front: `CoreCollection` | 0.7.4 | [Cadastro e lista](TASK_EXAMPLES.md#cadastro-e-lista); [metadata/CRUD](METADATA_CRUD_UI.md), [domínio](BACKEND_DOMAIN_MANIFEST.md) | CRUD valida escopo; consultas próprias também devem usar contexto autorizado |
+| Criar formulário | front: `useOonApi`, `CoreCollection` com formulário nativo | 0.7.4 | [Formulário e ação](PUBLIC_CONTRACTS.md#primeira-jornada-executável); [frontend](FRONTEND_API.md), [modal](DETAIL_MODAL_AND_RELATED_GRIDS.md) | Validação e permissão da UI não substituem backend |
+| Registrar rota privada | back: `defineRoutes`, `GenericError` | 0.7.4 | [Rota privada](PUBLIC_CONTRACTS.md#rotas-privadas); [backend](BACKEND_API.md) | Opções como segundo argumento, handler como terceiro; prefixo interno sem `/api` |
+| Executar ação | front: `useOonApi`; back: `defineRoutes` | 0.7.4 | [Formulário e ação](PUBLIC_CONTRACTS.md#primeira-jornada-executável); [rotas](ROUTES_HOOKS_WORKERS.md) | Valide permissão, entrada e efeitos no backend; retry de efeito externo é decisão do App |
+| Modelar esteira | `central.process.json`, back: `loadProcessManifest`; front: `CorePipeline` | 0.7.4 | [Esteira mínima](TASK_EXAMPLES.md#esteira); [processo](BACKEND_PROCESS_MANIFEST.md), [UI](COLLECTIONS_AND_PIPELINES.md) | Transições/invariantes não são fila genérica de integração |
+| Integrar sistema externo | back: `defineRoutes`, `GenericError`; serviço do App; Node `fetch` (não é API OonCore) | 0.7.4 | [Integração](TASK_EXAMPLES.md#integração); [contratos e segredo](PUBLIC_CONTRACTS.md) | Mapeamento, timeout, credenciais e recuperação de negócio pertencem ao App |
+| Armazenar credenciais | back: `capabilities.secrets.put/status/use/remove` | 0.7.6 | [Segredos V1](SECRETS.md); `/segredos` no exemplo | Apenas single_tenant dedicado; chave separada e responsabilidade de sanitização do consumidor |
+| Gerar PDF | back: `capabilities.pdf.render`; front: `useOonApi` | 0.6.0 | [Exemplo back/front e referência](PDF_RENDERING.md) | Depende de capability resolvida; limites de entrada/saída e timeout no guia |
+| Enviar e-mail | back: `capabilities.transactionalEmail.send`; front: `CoreTransactionalEmail` | 0.6.0 | [Exemplo de template, envio e painel](TRANSACTIONAL_EMAIL.md) | Sem anexos; `accepted` não confirma entrega; fila exclusiva de e-mail |
+| Diagnosticar | `GenericError`, HTTP `/health/ready`, `/health/version` | 0.7.4 | [Comandos](TASK_EXAMPLES.md#diagnóstico); [erros](ERRORS.md), [troubleshooting](TROUBLESHOOTING.md) | 404 HTML não é envelope de domínio; não colar segredos no diagnóstico |
+| Atualizar | CLI `create-central-oon docs sync/check` | 0.7.4 | [Comandos e referência](CORE_UPGRADE.md) | Atualize três pacotes, lockfiles e cache oficial; não edite `.ooncore` à mão |
+
+## Estado dos recursos
+
+- **Existente e público:** exports/contratos acima, CRUD/metadata, validações/fórmulas, manifesto de processo, auditoria, PDF e e-mail. [CAPABILITIES.md](CAPABILITIES.md) detalha os limites por ambiente.
+- **Interno, não consumível como contrato de integração:** stores, transports, registries internos, worker de e-mail e jobs de recálculo do processo. Mesmo funções exportadas para o processo não constituem uma API genérica de enqueue/claim/retry.
+- **Proposta futura separada:** execução durável genérica de integrações, diagnóstico padronizado operação → tentativa → troca e evolução de segredos. A existência de uma issue não disponibiliza uma API; não use `core.secrets` sem contrato publicado na versão instalada.
+
+A Plataforma homologada fornece identidade, acesso e delivery; o App não assume essa autoridade. Lacunas têm tratamento localizado conforme [AGENTS.md](AGENTS.md).
+
+
+## Jornada integrada e diagnóstico
+
+Na release __OONCORE_VERSION__, `create-central-oon example` instala o exemplo opt-in em uma base limpa; `create-central-oon doctor` diagnostica versões, lockfiles, manifestos, cache e erros de empacotamento. Veja [EXECUTABLE_EXAMPLE.md](EXECUTABLE_EXAMPLE.md).
+
+## Aplicação dos recursos nativos
+
+A página `/recursos` do exemplo demonstra fórmulas, validações, bindings, invariantes, documentos, dashboard e PDF. O serviço de e-mail é opt-in. Consulte [NATIVE_RESOURCES.md](NATIVE_RESOURCES.md) para o roteiro, helpers de escopo e limites reais de isolamento, auditoria e execução.

package/docs/TESTING_CONFORMANCE.md

@@ -1,30 +1,23 @@
 # Testes e conformidade
 
-## Gates do projeto consumidor
+## App consumidor
 
 ```bash
-npm run ooncore:docs:check
-npm run ooncore:conformance
 npm run check
-npm test
+npm run build --prefix frontend
 ```
 
-## Runtime local
+No scaffold, `check` executa `doctor`, que inclui docs check e conformance, versões instaladas, lockfiles e diagnóstico de composição. Rode também os testes relevantes declarados pelo App; a base neutra não cria um script raiz `test`. Prove a jornada com acesso permitido/recusado, validação de entrada, resultado e persistência quando aplicável. Não duplique verificações sem uma mudança ou risco concreto.
 
-Comprove:
+A homologação global da Plataforma e os testes de segurança do runtime pertencem ao SDK/Plataforma. O App preserva os contratos e comprova sua integração específica. Se alterar uma fronteira de segurança, cubra explicitamente essa mudança.
 
-- `127.0.0.1` e `localhost` funcionam;
-- `0.0.0.0`, IP de LAN, Host/Origin externos e proxy falham;
-- nenhuma chamada alcança a plataforma;
-- cookies existem e bearer não aparece no `localStorage`;
-- bootstraps de navegador e automação não podem ser reutilizados nem invalidar um ao outro;
-- expiração bloqueia a sessão e reiniciar o processo não amplia o prazo;
-- Apps multi-tenant recebem somente o contexto virtual fixo `local:tenant`;
-- perfis fora do manifesto falham;
-- CRUD, metadata, dashboards, processos e integrações locais funcionam;
-- `operationalRequestHeaders` falha fechado;
-- apagar o Mongo local inicia novo prazo, como limitação documentada.
+## Manutenção do SDK
 
-## Documentação
+Alterações no runtime exigem as provas pertinentes: loopback, sessão/CSRF, expiração, perfis, isolamento, recusa de identidade operacional local e ausência de chamadas à Plataforma. Esses cenários não são pré-requisito repetido para cada página de um App.
 
-`docs --check` valida fonte, versão, schema, entrada `AGENTS.md`, hashes dos documentos e entrypoints, além da presença de todos os arquivos. O tarball npm deve conter docs, templates e schemas. Exemplos devem compilar ou executar em CI.
+## Documentação distribuída
+
+`create-central-oon docs check` valida fonte, versão, schema, entrada, hashes e arquivos. `docs sync` regenera o cache a partir da fonte do pacote. O tarball deve conter docs, templates e schemas. Verifique links e exemplos alterados; build, publicação e homologação são evidências diferentes.
+
+
+No monorepo, `npm run check:authoring` executa os testes do gerador uma vez e verifica typecheck/build da base com o exemplo integrado. Execute após o build do SDK frontend. A suíte backend inclui HTTP real e MongoDB descartável para a mesma jornada; não simula router. No CI essas entradas substituem os checks duplicados.

package/docs/TRANSACTIONAL_EMAIL.md

@@ -64,7 +64,7 @@ async function enviarConfirmacao({ email, nome, idempotencyKey }, req) {
       to: email,
       variables: { nome },
       idempotencyKey,
-      correlationId: req.id,
+      correlationId: req.correlationId,
       maxAttempts: 5,
     },
     {

package/examples/first-journey/FIRST_JOURNEY.md

@@ -0,0 +1,27 @@
+# Primeira jornada executável
+
+Exemplo opt-in instalado depois da base oficial. O comando exige routes.tsx/navigation.ts originais e recusa colisões antes de escrever. Não é scaffold alternativo nem migração de App existente.
+
+1. Instale as dependências e configure MongoDB como replica set (as invariantes exigem transações; um Mongo standalone não atende este exemplo ampliado).
+2. Execute `npm run dev` e abra **Primeira jornada** no menu. Selecione admin no banner local.
+3. Envie o formulário e valide nome vazio; cadastre uma Pessoa, consulte a lista e recarregue.
+4. Crie um Ticket em Aberto e mova para Concluído. O backend recusa voltar para Aberto.
+5. Configure `INTEGRACAO_URL` (HTTPS controlado por você) e `INTEGRACAO_TOKEN` exclusivamente no ambiente backend. Reinicie e clique em Testar integração externa. Nada é enviado à Plataforma pelo exemplo local.
+6. Selecione viewer: as operações devem retornar 403. A página continua visível para demonstrar o diagnóstico da recusa; permissão de menu não substitui a autorização backend.
+7. Reinicie o App e confira os registros. Execute `npm run check` e `npm run build --prefix frontend`.
+
+Pessoa usa escopo tenant explícito. Ticket declarativo limita-se a single_tenant dedicado: nesta versão o domain manifest não propaga escopo de linha; não reutilize essa model em multi_tenant.
+
+A ação de processo usa o PATCH do CRUD e a transição do process manifest; não implementa worker ou integração fiscal. A rota externa só consulta o destino configurado, não aceita URL/token da UI, não repete efeitos externos e devolve apenas mensagem/status sanitizados. `sensitiveBody` omite request/response no requestLog; não cifra banco. Este exemplo não cadastra nem persiste credenciais.
+
+Com baseURL `/api`, `http.post('/integracao/testar')` chama publicamente `/api/integracao/testar`; o proxy existente remove `/api` e o Core recebe `/integracao/testar`. Não duplique o prefixo. O bootstrap programático deve apontar `cwd` para backend/; somente .js/.cjs dos diretórios documentados são descobertos.
+
+A suíte do SDK testa o mesmo código com HTTP real, sessão/CSRF, MongoDB descartável, HTTPS de teste, recusa de acesso, persistência após reinício e estrutura de runtime backend/ + central.app.json. Isso não equivale à homologação pública do emissor nem ao teste de uma imagem Docker final.
+
+## Recursos nativos
+
+Abra **Recursos nativos** no menu e siga `.ooncore/docs/NATIVE_RESOURCES.md`: Contratos → Parcelas → Documentos → Indicadores → PDF. Contrato/Parcela também são restritos ao banco single-tenant dedicado. PDF requer capability resolvida; e-mail é opt-in, com serviço e template distribuídos, sem envio ao instalar. As models declarativas deste exemplo dependem do banco dedicado; declare escopo explícito quando necessário.
+
+## Segredos opt-in
+
+O exemplo declara core.secrets e adiciona `/segredos` com dois nomes e credenciais em objeto. Siga `.ooncore/docs/SECRETS.md` para configurar a chave local, salvar/consultar/utilizar/substituir/remover e os limites do callback. Sem provisionamento, as outras jornadas continuam disponíveis.