@softize/opus 24.0.1 → 25.0.0

package/bin/lib/gen-runner.mjs

@@ -90,7 +90,7 @@ async function main() {
   const opusCoreUrl = pathToFileURL(
     path.join(PACKAGE_ROOT, "src", "core", "index.ts"),
   ).href;
-  const { flattenDomain } = await import(opusCoreUrl);
+  const { flattenDomain, domainPurges, declaredJsonSchema } = await import(opusCoreUrl);
 
   const opusSeedUrl = pathToFileURL(
     path.join(PACKAGE_ROOT, "src", "seed", "index.ts"),
@@ -137,7 +137,10 @@ async function main() {
 
   const ctx = {
     flattenDomain,
+    domainPurges,
+    // Standard Schema que declara o próprio JSON Schema (ADR 0051) dispensa o zod.
     toJsonSchema: (schema) =>
+      declaredJsonSchema(schema, { target: "openapi-3.0" }) ??
       zodToJsonSchema(schema, { target: "openApi3", $refStrategy: "none" }),
     sourceConfigDir: path.dirname(configAbs),
   };
@@ -150,7 +153,7 @@ async function main() {
   }
   const actionRegistry = Object.fromEntries(
     cfg.domains
-      .flatMap((domain) => collectDomainActions(domain))
+      .flatMap((domain) => collectDomainActions(domain, ctx))
       .map((action) => [action.name, action]),
   );
   const presentations = validatePresentations(
@@ -185,12 +188,15 @@ async function main() {
   emit({ ok: true, payload });
 }
 
-function collectDomainActions(domain) {
+function collectDomainActions(domain, ctx, parentPath = []) {
   const actions = Array.from(iterateActions(domain.actions));
+  for (const purge of ctx.domainPurges(domain, parentPath)) actions.push(purge.action);
   for (const subdomain of Array.isArray(domain.subdomains)
     ? domain.subdomains
     : []) {
-    actions.push(...collectDomainActions(subdomain));
+    actions.push(
+      ...collectDomainActions(subdomain, ctx, [...parentPath, domain.name]),
+    );
   }
   return actions;
 }
@@ -206,8 +212,11 @@ function serializeSeed(seed, isSeedDefinition, publicSeedDefinition) {
 // Serialização
 // =============================================================================
 
-function serializeDomain(domain, ctx) {
+function serializeDomain(domain, ctx, parentPath = []) {
   const entityList = serializeEntities(domain.entities);
+  // Expurgo derivado das entidades com retenção (ADR 0051): a action e a rotina entram no
+  // manifest no domínio que lista a entidade, como as declaradas.
+  const purges = ctx.domainPurges(domain, parentPath);
   return {
     name: domain.name,
     description: nullable(domain.description),
@@ -216,17 +225,21 @@ function serializeDomain(domain, ctx) {
     entities: entityList,
     dataProducts: serializeDataProducts(domain.dataProducts),
     dicts: serializeDicts(domain.dicts),
-    actions: Array.from(iterateActions(domain.actions), (a) =>
-      serializeAction(a, ctx),
-    ),
+    actions: [
+      ...iterateActions(domain.actions),
+      ...purges.map((purge) => purge.action),
+    ].map((a) => serializeAction(a, ctx)),
     reactions: Array.isArray(domain.reactions)
       ? domain.reactions.map(serializeReaction)
       : [],
-    schedules: Array.isArray(domain.schedules)
-      ? domain.schedules.map(serializeSchedule)
-      : [],
+    schedules: [
+      ...(Array.isArray(domain.schedules) ? domain.schedules : []),
+      ...purges.map((purge) => purge.schedule),
+    ].map(serializeSchedule),
     subdomains: Array.isArray(domain.subdomains)
-      ? domain.subdomains.map((s) => serializeDomain(s, ctx))
+      ? domain.subdomains.map((s) =>
+          serializeDomain(s, ctx, [...parentPath, domain.name]),
+        )
       : [],
   };
 }

package/bin/lib/mcp.mjs

@@ -42,7 +42,7 @@ export function buildServer() {
   server.registerTool(
     'opus_check',
     {
-      description: 'Valida as convenções das actions (régua) — defineAction e o split defineContract+bindAction: naming, kind, ordem dos campos, export, requires-sem-authorize, ignored-by-kind. Retorna findings.',
+      description: 'Valida as convenções das actions (régua) — defineAction e o split defineContract+bindAction: naming, kind, ordem dos campos, export, requires-sem-authorize, ignored-by-kind, soft-delete-retention. Retorna findings.',
       inputSchema: { dir: z.string().optional() },
     },
     async ({ dir }) => asText(await scanDir(dirOf(dir))),

package/docs/adr/0050-markdown-does-not-load-external-images.md

@@ -0,0 +1,64 @@
+# ADR 0050 — Markdown não carrega imagem externa
+
+- **Status:** aceita.
+- **Data:** 2026-10-02.
+- **Complementa:** a decisão registrada em `markdown.tsx` de renderizar com `html: false`, porque o
+  conteúdo vem de pessoas e de modelos.
+
+## Contexto
+
+O `Markdown` é o renderer único do pacote: o chat, os painéis e a documentação usam a mesma
+instância do markdown-it. Ele já escapa HTML do fonte e o markdown-it já recusa links
+`javascript:` e `data:text/html`. Faltava uma terceira via: `![](https://host/x.png?d=…)` virava um
+`<img>` que o navegador busca sozinho, sem nenhum clique.
+
+Isso importa porque boa parte desse conteúdo é escrita por um modelo. Um modelo induzido por
+injeção de prompt (um documento, uma resposta de ferramenta, uma mensagem de terceiro) pode montar
+o endereço de uma imagem com dados da conversa e deixar que o navegador de quem lê os entregue ao
+host. Num relatório salvo, isso acontece também com quem abre o relatório depois.
+
+Nenhum consumidor conhecido depende de imagem externa no Markdown: a documentação do pacote não usa
+imagem em Markdown, e a plataforma Grand Brasil não tem imagem externa em documentos, Base de
+conhecimento nem relatórios.
+
+## Decisão
+
+1. O `Markdown` não renderiza `<img>` para endereço absoluto, com esquema (`https:`, `http:`) ou
+   relativo ao protocolo (`//host`). No lugar da imagem fica o texto alternativo dela, num
+   `span` com `data-slot="markdown-external-image"`, sem link: seguir o endereço exigiria um
+   clique, mas um link montado pelo modelo não deve ser oferecido como se fosse da imagem.
+2. Endereço relativo (`/caminho`, `./arquivo.png`) continua renderizando a imagem, porque é servido
+   pela própria aplicação. As imagens em `data:` que o markdown-it já aceita (`png`, `gif`, `jpeg`,
+   `webp`) também continuam: não fazem requisição.
+3. A regra vale para a instância compartilhada `markdownIt`, então chat, painéis e documentação
+   seguem o mesmo comportamento. Não há opção para liberar imagem externa; um consumidor que
+   precise disso traz o caso concreto para uma decisão nova.
+
+## Consequências
+
+- Uma resposta ou um relatório com imagem externa mostra o texto alternativo no lugar da imagem.
+- A defesa não depende de cada aplicação configurar uma Content Security Policy com `img-src`,
+  embora uma CSP continue sendo uma segunda camada recomendada.
+- Imagem absoluta da própria origem também deixa de carregar. Não há uso conhecido; se aparecer,
+  o caminho é usar o endereço relativo.
+- A imagem relativa continua fazendo uma requisição à própria origem, com os cookies de quem lê. Se
+  a aplicação tiver um redirecionamento aberto ou um proxy de imagem, o mesmo vetor volta por ali.
+  É mais um motivo para manter a CSP com `img-src` como segunda camada.
+
+## Alternativas consideradas
+
+- **Bloquear toda imagem.** Fecharia também o resíduo da imagem relativa, mas tiraria imagens que a
+  própria aplicação serve (anexos, ilustrações de documentação) sem um vetor conhecido que o
+  justifique hoje.
+- **Transformar a imagem externa em link.** Mantém o endereço acessível, mas oferece com aparência
+  legítima um link montado pelo modelo; o texto alternativo basta para a leitura.
+- **Lista de origens permitidas ou proxy de imagem.** Exigiriam configuração por aplicação e um
+  serviço novo para um uso que não existe. Ficam para quando um consumidor trouxer o caso.
+- **Só CSP na aplicação.** Depende de cada consumidor configurar e não vale fora do navegador da
+  aplicação (por exemplo, na documentação publicada). Fica como segunda camada, não como a defesa.
+
+## Verificação
+
+- Teste do `Markdown`: imagem `https:`, `//host`, com maiúsculas, com esquema em entidade, por
+  referência, dentro de link e em célula de tabela não geram `<img>` e mostram o texto alternativo;
+  imagem relativa e `data:image/png` continuam gerando `<img>`.

package/docs/adr/0051-soft-delete-declares-retention-and-purge.md

@@ -0,0 +1,224 @@
+# ADR 0051 — Exclusão lógica declara retenção e expurgo
+
+- **Status:** aceita.
+- **Data:** 2026-10-02.
+- **Complementa:** ADR 0028, que roda actions agendadas como o sistema, e ADR 0002, cujo par
+  declaração e binding serve de molde.
+
+## Contexto
+
+`defineEntity({ softDelete: true })` injeta a coluna `deletedAt`. Pelo `kyselyRepo`, excluir passa a
+marcar a data, e `findById`, `all` e `list` deixam os registros excluídos de fora. O ciclo fica pela
+metade: o Opus sabe excluir de forma lógica, mas nada diz quando o registro sai de vez.
+
+Sem esse fechamento, cada consumidor resolve sozinho. A plataforma Grand Brasil é o caso concreto:
+
+- os fluxos de automação fazem exclusão lógica e expurgo à mão, com coluna própria e uma action
+  `automation.purge-deleted` escrita no domínio. Ela é restrita ao sistema e à administração, é
+  interna e roda numa rotina diária;
+- os relatórios ainda apagam de vez. Por isso, excluir um relatório cuja conversa de IA registrou
+  uma autorização de extração de dado pessoal esbarra numa escolha ruim: apagar a autorização
+  junto, contra a regra que manda guardá-la, ou impedir a exclusão.
+
+A forma escolhida para os relatórios é a mesma dos fluxos: excluir de forma lógica, manter o
+histórico durante um prazo e expurgar depois, numa rotina. Com dois casos, o padrão já se repete.
+No terceiro, quem esquecer o expurgo deixa registros excluídos acumulando para sempre, inclusive
+dado pessoal, sem que nada avise.
+
+O que precisa ser verdadeiro:
+
+- toda entidade com exclusão lógica tem um prazo de retenção declarado ou declara, com motivo, que
+  guarda para sempre;
+- o expurgo existe, roda sozinho, só o sistema o executa e deixa rastro do que apagou;
+- o prazo prometido é cumprido: nada expurga antes dele;
+- a ordem do que se apaga e o que se preserva continuam sendo decisão do domínio, porque variam:
+  um fluxo leva junto as execuções, e um relatório precisa apagar conversas em outro serviço e
+  preservar o consumo de IA;
+- a falta de declaração quebra a verificação, em vez de depender de alguém lembrar.
+
+## Decisão
+
+### 1. A retenção é declarada na entidade
+
+`softDelete` passa a aceitar um objeto, numa de duas formas mutuamente exclusivas:
+
+```ts
+type SoftDelete =
+  | true // aceito pelo tipo; reprovado pelo `opus check` (seção 6)
+  | {
+      retainDays: number          // inteiro positivo; conta a partir de `deletedAt`
+      timezone: string            // IANA, obrigatório: a rotina não depende do fuso da máquina
+      label: string               // título da action, completo: 'Expurgar relatórios excluídos'
+      description: string         // descrição da action, completa
+      schedule?: { cron?: string; enabled?: boolean } // padrão: '30 3 * * *', habilitada
+      batchSize?: number          // padrão: 200 linhas por lote; no máximo 10_000
+      maxDurationMs?: number      // padrão: 60_000 por execução
+    }
+  | { retain: 'forever'; reason: string }
+```
+
+Toda forma diferente de `true` mantém a exclusão lógica. Os pontos do pacote que hoje testam
+`softDelete === true` passam por uma única função, `hasSoftDelete(entity)`, que reconhece as três:
+`entityColumns` (injeção de `deletedAt`), o tipo `SoftDeletePart` e o `kyselyRepo` (filtro de
+leitura e exclusão lógica). Sem isso, a forma de objeto deixaria de injetar a coluna e de filtrar,
+sem erro nenhum.
+
+### 2. Uma entidade com retenção pertence a exatamente um domínio
+
+A action e a rotina do expurgo nascem no domínio que lista a entidade em `entities`.
+
+- A mesma entidade com retenção em dois domínios, ou num domínio e num subdomínio dele, falha com
+  `domain.entity_registered_twice`: no `validateDomain`, dentro da árvore de um domínio, e no
+  `register` do runtime, entre domínios registrados separadamente. A comparação é pela tabela, para
+  pegar também duas declarações `defineEntity` da mesma tabela, que gerariam dois expurgos dela.
+- Entidade com `retainDays` que não aparece em nenhum `entities` de domínio é reprovada pelo
+  `opus check`. O check liga a entidade ao domínio pelo identificador exportado, como já liga um
+  `bindAction` ao seu contrato. Assim, uma entidade usada só por repositório não fica sem expurgo.
+
+### 3. O que o Opus gera
+
+`flattenDomain` deriva, de cada entidade com `retainDays`, um contrato e uma rotina, e a checagem de
+duplicidade do `validateDomain` passa a incluí-los. A derivação é pura e isomorfa, como o resto do
+`flattenDomain`.
+
+**Nomes.** A action se chama `<caminho-do-domínio>.<entidade-em-kebab>.purge-deleted`. Quando a
+entidade em kebab é igual ao último segmento do domínio, o segmento não se repete: a entidade
+`automation` no domínio `automation` gera `automation.purge-deleted`, e a entidade `reportShare` no
+domínio `report` gera `report.report-share.purge-deleted`. A rotina se chama `<action>.daily`. O
+caminho do domínio entra como está, sem conversão, como nas demais actions do domínio.
+
+**Contrato da action:**
+
+- entrada `{ olderThanDays?: number }`: inteiro, no mínimo o `retainDays` e no máximo 3650. O
+  padrão é o `retainDays`. Expurgar antes do prazo é recusado, para cumprir a retenção declarada;
+- saída `{ purged: number }`;
+- `effect: 'write'`, `automatable: true`, `internal: true` (não fica exposta por REST),
+  `personalData: false` e `ai: false`. O motivo de ficar fora da IA (é operação do sistema, não
+  pedido de uma pessoa) fica registrado no fonte do SDK, porque a `description` é do consumidor;
+- autorização: só o sistema (`isSystemActor`). Não há execução manual por pessoa nesta decisão;
+- textos: o `label` e a `description` declarados na retenção, completos e literais. O Opus não
+  monta frase a partir do nome do recurso, porque um modelo fixo erra a concordância (um recurso
+  feminino viraria "conversas excluídos"). O `opus copy` passa a ler esses dois campos no
+  `defineEntity`, como já lê os textos de `defineContract`.
+
+**Rotina:** `defineSchedule` com a action, `cron` (padrão `'30 3 * * *'`), o `timezone` declarado e
+`enabled` (padrão verdadeiro). Ela roda como o sistema, conforme a ADR 0028. Como qualquer rotina,
+exige um `SchedulerAdapter` no `start()`, mesmo com `enabled: false`.
+
+### 4. Quem executa: handler padrão ou `bindPurge`
+
+O contrato é gerado no core. O handler é anexado no servidor:
+
+- **Padrão:** quando o runtime tem um `DataAdapter` Kysely, o `register` anexa o handler padrão.
+  Ele apaga as linhas com `deletedAt` anterior ao corte, das mais antigas para as mais novas, em
+  lotes de `batchSize`. Repete os lotes até não sobrar nada ou até esgotar `maxDurationMs`.
+- **Próprio:** quando apagar a linha não basta, o domínio liga `bindPurge(entity, handler)` e o
+  registra em `purges` no `defineDomain`. `isDomainConfig` passa a reconhecer `purges`. O handler
+  recebe `{ ctx, cutoff, batchSize }`, apaga um lote e devolve `{ ids: string[] }`. O Opus repete os
+  lotes enquanto houver ids e tempo, e continua dono do contrato, da rotina, dos lotes e do registro.
+  Respeitar o `cutoff` é obrigação do handler: o Opus recusa um `olderThanDays` abaixo do prazo, mas
+  só o handler decide o que apaga. Um lote que devolve um id já removido na mesma execução, ou mais
+  ids que o `batchSize`, interrompe o expurgo com `purge.no_progress`; sem essa guarda, um handler
+  que não avança repetiria lotes até o fim do tempo. Antes de parar, o Opus registra os ids novos
+  daquele lote, que o handler já apagou. Entre um lote e outro, o Opus cede a vez ao event loop.
+  Ele decide a ordem, o que fica e o que sai em outro serviço. É a separação da ADR 0002: a entidade,
+  com a retenção, fica no contrato; o handler fica no servidor.
+- **Sem handler padrão aplicável e sem `bindPurge`**, por exemplo sem `DataAdapter` ou com um que não
+  seja Kysely: o `start()` recusa com `runtime.purge_handler_missing`, nomeando a entidade.
+- **No modo design**, a action gerada se comporta como as demais: entra no catálogo, e o handler é o
+  do design. As rotinas não são iniciadas.
+
+**Dependências no banco:** o schema do Opus não declara cascata; ela depende da DDL do consumidor.
+Se uma chave estrangeira restritiva impedir a exclusão, a execução agendada falha com o erro do
+banco no log e na auditoria da execução, e nada é apagado daquele lote. Como a linha travada está
+entre as mais antigas, ela volta ao primeiro lote em toda execução: o expurgo da entidade fica
+parado até a chave ser ajustada. A saída é ajustar a chave, com cascata na DDL, ou usar `bindPurge`
+para apagar os dependentes primeiro.
+
+### 5. O registro do que saiu
+
+Cada lote que apaga algo registra a chave `opus.purge`, com a entidade, a action, o corte, o
+`olderThanDays`, o número do lote e os ids removidos, em blocos de no máximo 500 ids. Assim, um
+acúmulo grande vira vários registros de tamanho limitado, nunca uma linha sem teto. No fim da
+execução que apagou algo, `opus.purge.total` traz a quantidade, o número de lotes e se restou
+trabalho: verdadeiro quando a execução parou por tempo com lote cheio ou foi interrompida por erro.
+Os registros vão para o `ctx.log` quando existe e, senão, para o logger do runtime. Os únicos rastros
+de um expurgo são esses registros e a auditoria da execução agendada.
+
+### 6. O `opus check` cobra a regra
+
+A regra `soft-delete-retention` reprova:
+
+- entidade com `softDelete: true`, sem retenção;
+- `retain: 'forever'` sem `reason`;
+- `retainDays` sem `timezone`, `label` ou `description`, ou com valor que não é inteiro positivo
+  ou passa de 3650, e `batchSize` que não é inteiro positivo ou passa de 10.000;
+- entidade com `retainDays` fora de qualquer `entities` de domínio;
+- `bindPurge` para uma entidade sem `retainDays`;
+- `bindPurge` exportado que não aparece no `purges` de nenhum domínio, porque cairia em silêncio no
+  handler padrão.
+
+### 7. Documentação
+
+`docs/protocol.md` e `docs/data-layer.md` passam a mostrar a forma com retenção e deixam de
+apresentar `softDelete: true` como suficiente. O trecho de `protocol.md` que promete uma "opção
+explícita" para incluir excluídos na leitura é corrigido: essa opção não existe hoje.
+
+### 8. O que fica fora
+
+- Restaurar um registro excluído dentro do prazo. É útil, mas independente do expurgo, e entra
+  quando houver o caso.
+- Execução manual do expurgo por uma pessoa.
+- Um motor de retenção para o que não é entidade com exclusão lógica, como logs e trilhas de
+  auditoria. Eles têm política própria.
+- A introspecção estática usada pelo MCP de desenvolvimento ainda não mostra a action e a rotina
+  geradas; o manifest mostra.
+
+## Consequências
+
+- Quem usa `softDelete: true` precisa declarar a retenção ou o motivo para guardar. O `opus check`
+  passa a cobrar isso, então a versão é major, com a migração no changelog.
+- O expurgo deixa de ser código repetido em cada domínio. O terceiro caso já nasce com prazo,
+  rotina, lotes, autorização e registro, e o esquecimento quebra a verificação.
+- A action de expurgo aparece no manifest e na documentação, e a rotina na lista de agendamentos.
+  Fica visível o que cada projeto apaga e quando.
+- O expurgo é irreversível: depois dele, restam só o registro `opus.purge` e a auditoria.
+
+## Alternativas consideradas
+
+- **Manter o expurgo no consumidor, com uma convenção escrita.** É o estado de hoje. Não há
+  garantia: o próximo domínio pode esquecer, e nada avisa.
+- **Contrato e teste de gate só no consumidor.** Resolveria a Grand Brasil, mas deixaria o
+  padrão fora do lugar onde a exclusão lógica já mora, e cada projeto repetiria o gate.
+- **Expurgo implícito, sem declarar prazo.** Um padrão único, por exemplo 30 dias, para toda
+  entidade com `softDelete`. Esconderia uma decisão de retenção, que pode envolver dado pessoal,
+  atrás de um padrão silencioso.
+- **Fuso padrão do projeto em vez de fuso por entidade.** Seria menos repetitivo, mas o pacote não
+  tem esse padrão hoje, e o check, que é estático, não conseguiria verificá-lo. Fica para quando
+  houver uma configuração de projeto para agendamentos.
+- **Um motor genérico de retenção para qualquer tabela.** Cobriria logs e trilhas, mas mistura
+  políticas diferentes e é cedo demais com os casos que existem.
+
+## Verificação
+
+- Testes do SDK:
+  - a forma de objeto mantém a exclusão lógica: injeta `deletedAt` e o `kyselyRepo` filtra e marca;
+  - a entidade com `retainDays` gera a action e a rotina com os nomes da seção 3, incluindo o caso de
+    entidade em kebab diferente do domínio, e com as declarações de contrato e autorização;
+  - entrada abaixo do `retainDays` é recusada, e chamador que não é o sistema também;
+  - o handler padrão apaga só os excluídos antes do corte, em lotes, do mais antigo para o mais novo,
+    para no tempo e registra `opus.purge` com os ids, em blocos limitados, e `opus.purge.total`;
+  - uma linha restaurada ou excluída de novo entre a seleção e a exclusão não é apagada;
+  - um handler que repete ids ou excede o `batchSize` falha com `purge.no_progress`, rápido e sem
+    inflar o registro, e os ids novos do lote que parou entram no registro e no total;
+  - o `bindPurge` substitui o padrão e mantém contrato, lotes e registro;
+  - entidade em dois domínios, ou duas entidades da mesma tabela, falham com
+    `domain.entity_registered_twice`;
+  - o `start()` sem handler falha com `runtime.purge_handler_missing`;
+  - chave estrangeira restritiva faz a execução falhar sem apagar o lote, e a seguinte também;
+  - o core (`src/core/index.ts`) continua sem pacote externo em tempo de execução: os schemas da
+    action gerada são Standard Schema com o JSON Schema anexado, sem zod.
+- Testes do `opus check`: os seis casos da seção 6 reprovam, e a declaração completa passa.
+- Teste do `opus copy`: o `label` e a `description` da retenção entram no inventário.
+- Na Grand Brasil, a adoção migra os fluxos de automação para `softDelete` com retenção e cria a
+  exclusão lógica dos relatórios com expurgo próprio.

package/docs/data-layer.md

@@ -137,7 +137,13 @@ export const Deal = defineEntity({
   },
   relations: { owner: belongsTo('user', { from: 'ownerId' }) },
   timestamps: true,
-  softDelete: true,
+  // Exclusão lógica com prazo: o Opus gera a action e a rotina de expurgo (ADR 0051).
+  softDelete: {
+    retainDays: 90,
+    timezone: 'America/Sao_Paulo',
+    label: 'Expurgar negócios excluídos',
+    description: 'Apaga de vez os negócios excluídos há mais de 90 dias.',
+  },
 })
 ```
 
@@ -194,6 +200,25 @@ defineAction({
 })
 ```
 
+### 6. Expurgo dos excluídos
+Com `retainDays`, `remove` marca `deletedAt`, e o domínio que lista a entidade em `entities`
+ganha a action `deal.purge-deleted` e a rotina `deal.purge-deleted.daily` (ADR 0051). Com
+`kyselyData` no runtime, o handler padrão apaga em lotes, do mais antigo para o mais novo, as
+linhas excluídas há mais de `retainDays`. A rotina exige um `SchedulerAdapter`.
+
+```ts
+import { defineDomain } from '@softize/opus'
+
+export const deal = defineDomain({ name: 'deal', entities: { Deal } })
+// runtime.register([deal]) → deal.purge-deleted + deal.purge-deleted.daily
+```
+
+Quando apagar a linha não basta, registre um `bindPurge` (de `@softize/opus/data`) em `purges`
+no mesmo domínio. Uma chave estrangeira restritiva faz a execução falhar sem apagar o lote, e como a
+linha travada está entre as mais antigas, toda execução seguinte falha do mesmo jeito: o expurgo da
+entidade fica parado até a chave ser ajustada (cascata na DDL) ou um `bindPurge` apagar os
+dependentes primeiro. Detalhes em `protocol.md`, §15, "Retenção e expurgo".
+
 ## Naming (camel ↔ snake)
 
 O backend é **100% camelCase** (TS idiomático); o snake_case mora só no banco. Quem
@@ -233,7 +258,7 @@ export default {
 2. ✅ `diffColumns` (puro) + `desiredColumns` + `kyselyDriftCheck`.
 3. ✅ Grupo CLI `db` + `opus db check` (carrega config via tsx, factory `database()`).
 4. ✅ `kyselyRepo(db, entity)` — CRUD tipado (insert/findById/update/remove/list),
-   gera id (pk auto), preenche timestamps, respeita soft-delete. Falta o açúcar
+   gera id (pk auto), preenche timestamps, respeita a exclusão lógica. Falta o açúcar
    `ctx.repo(Entity)` (wiring na ActionContext).
 5. ✅ `opus db migrate` — schema idempotente evolutivo (SQL, config `schema`) + drift-check
    embutido. (A 1ª versão era Kysely Migrator; aposentada — o formato nunca pegou.)
@@ -252,4 +277,7 @@ export default {
    Esquecer o plugin → o `db check` falha e expõe (footgun auto-denunciado).
 10. Aprofundar o drift (índices/FK/tipos/defaults).
 11. Cursor pagination + `FilterSpec` ricos no search (hoje offset + igualdade).
-12. (Opt-in) drivers de auto-gen: drizzle-kit / Atlas.
+12. ✅ Retenção da exclusão lógica (ADR 0051): `softDelete` declara `retainDays` ou
+    `retain: 'forever'`; o domínio gera a action e a rotina de expurgo, com o handler padrão no
+    `kyselyData` ou o próprio em `bindPurge`. Restaurar um excluído dentro do prazo fica fora.
+13. (Opt-in) drivers de auto-gen: drizzle-kit / Atlas.

package/docs/protocol.md

@@ -1942,7 +1942,12 @@ export const Deal = defineEntity({
   ],
 
   timestamps: true,
-  softDelete: true,
+  softDelete: {
+    retainDays: 90,
+    timezone: 'America/Sao_Paulo',
+    label: 'Expurgar negócios excluídos',
+    description: 'Apaga de vez os negócios excluídos há mais de 90 dias.',
+  },
 })
 ```
 
@@ -1964,7 +1969,7 @@ fields: { code: t.string().pk(), /* ... */ }   // sem id automático
 
 **Timestamps.** `timestamps: true` injeta `createdAt` e `updatedAt` (geridos pelo runtime — o handler nunca seta na mão). Default é `false`.
 
-**Soft delete.** `softDelete: true` injeta `deletedAt`. Actions `search`/`view` filtram registros deletados por default; passe a opção explícita quando quiser incluí-los.
+**Exclusão lógica.** `softDelete` injeta `deletedAt`. Pelo `kyselyRepo`, `remove` marca a data em vez de apagar, e `findById`, `all` e `list` deixam os excluídos de fora; não há opção para incluí-los na leitura, e uma consulta escrita à mão aplica o filtro por conta própria. A declaração diz também quando o registro excluído sai de vez: `retainDays` com o fuso e os textos da action de expurgo, ou `{ retain: 'forever', reason }`. `softDelete: true` ainda é aceito pelo tipo, mas o `opus check` o reprova. Veja [Retenção e expurgo](#retenção-e-expurgo).
 
 ### Campos
 
@@ -2118,6 +2123,97 @@ export const crm = defineDomain({
 })
 ```
 
+### Retenção e expurgo
+
+Uma entidade com exclusão lógica declara por quanto tempo guarda o registro excluído. Sem esse
+prazo, os excluídos se acumulam para sempre, inclusive dado pessoal, sem que nada avise. Há duas
+formas, e a escolha é do domínio (ADR 0051):
+
+```ts
+// Prazo: o registro excluído sai de vez depois de 90 dias.
+softDelete: {
+  retainDays: 90,                       // inteiro de 1 a 3650, contado a partir de deletedAt
+  timezone: 'America/Sao_Paulo',        // fuso da rotina; obrigatório
+  label: 'Expurgar negócios excluídos', // título da action de expurgo, completo
+  description: 'Apaga de vez os negócios excluídos há mais de 90 dias.',
+  schedule: { cron: '30 3 * * *', enabled: true }, // opcional; estes são os padrões
+  batchSize: 200,                       // opcional; linhas por lote, até 10_000
+  maxDurationMs: 60_000,                // opcional; tempo máximo de uma execução
+}
+
+// Guarda para sempre, com o motivo.
+softDelete: { retain: 'forever', reason: 'Exigência legal de guarda do histórico.' }
+```
+
+O `label` e a `description` entram na action como estão: o Opus não monta a frase a partir do nome
+do recurso, porque um modelo fixo erraria a concordância. O `opus copy` os lê no `defineEntity`.
+
+**O que o Opus gera.** Para cada entidade com `retainDays`, o domínio que a lista em `entities`
+ganha uma action e uma rotina. A action se chama `<caminho-do-domínio>.<entidade-em-kebab>.purge-deleted`;
+quando a entidade em kebab é igual ao último segmento do domínio, ele não se repete. A entidade
+`deal` no domínio `deal` gera `deal.purge-deleted`, e `dealNote` no domínio `crm` gera
+`crm.deal-note.purge-deleted`. A rotina se chama `<action>.daily`.
+
+| Peça | Declaração |
+|---|---|
+| Entrada | `{ olderThanDays?: number }`: inteiro entre o `retainDays` e 3650, com o `retainDays` como padrão. Expurgar antes do prazo é recusado. |
+| Saída | `{ purged: number }` |
+| Natureza | `kind: 'simple'`, `effect: 'write'`, `personalData: false` |
+| Acesso | `automatable: true` e `authorize` que aceita só o sistema (`isSystemActor`); `internal: true` (fora do REST) e `ai: false` (é operação do sistema, não pedido de uma pessoa) |
+| Rotina | `cron` declarado ou `'30 3 * * *'`, no `timezone` declarado, executada como o sistema (ADR 0028) |
+
+A mesma entidade com retenção em dois domínios, ou num domínio e num subdomínio dele, falha com
+`domain.entity_registered_twice`; a comparação é pela tabela, então duas declarações da mesma
+tabela também falham. A checagem de nomes duplicados do domínio inclui a action e a
+rotina geradas.
+
+**Quem apaga.** O contrato nasce no core; o handler é anexado no servidor, no `register`:
+
+- com o `DataAdapter` do driver Kysely, vale o handler padrão. Ele apaga as linhas com `deletedAt`
+  anterior ao corte, das mais antigas para as mais novas, em lotes de `batchSize`, até não sobrar
+  nada ou até esgotar `maxDurationMs`;
+- quando apagar a linha não basta, o domínio liga um handler próprio com `bindPurge`, de
+  `@softize/opus/data`, e o registra em `purges` no mesmo `defineDomain`. O handler recebe
+  `{ ctx, cutoff, batchSize }`, apaga um lote e devolve `{ ids }`; o Opus repete os lotes enquanto
+  houver ids e tempo. O handler precisa respeitar o `cutoff`: a garantia de nunca expurgar antes do
+  prazo depende dele. Um id repetido na mesma execução, ou mais ids que o `batchSize`, interrompe o
+  expurgo com `purge.no_progress`, para que um handler que não avança não repita lotes até o fim do
+  tempo. Os ids novos desse lote, que o handler já apagou, entram no registro antes da parada;
+- sem nenhum dos dois, o `start()` recusa com `runtime.purge_handler_missing`, nomeando a entidade.
+
+```ts
+import { bindPurge } from '@softize/opus/data'
+
+export const dealPurge = bindPurge(Deal, async ({ ctx, cutoff, batchSize }) => {
+  // apaga os anexos em outro serviço e depois as linhas; devolve os ids que saíram
+  const ids = await purgeDealsWithAttachments(ctx, cutoff, batchSize)
+  return { ids }
+})
+
+export const crm = defineDomain({ name: 'crm', entities: { Deal }, purges: [dealPurge] })
+```
+
+A rotina exige um `SchedulerAdapter`, como qualquer schedule. No modo design, a action entra no
+catálogo, sem rota HTTP porque é `internal`, e a rotina não inicia.
+
+Os schemas da action são Standard Schema escritos pelo Opus, sem zod, com o JSON Schema anexado
+em `~standard.jsonSchema`. O manifest, o OpenAPI e o MCP leem esse JSON Schema antes de recorrer
+ao zod, então `@softize/opus` continua carregando sem zod instalado.
+
+**Dependências no banco.** O schema do Opus não declara cascata. Se uma chave estrangeira
+restritiva recusar a exclusão, a execução falha com o erro do banco no log e na auditoria, e nada
+daquele lote é apagado. Como a linha travada está entre as mais antigas, ela volta ao primeiro lote
+em toda execução: o expurgo da entidade fica parado até a chave ser ajustada. Antes de declarar
+`retainDays`, confira as chaves que apontam para a tabela; use cascata na DDL ou um `bindPurge`
+que apague os dependentes primeiro.
+
+**O registro.** Cada lote que apaga algo registra `opus.purge` com a entidade, a action, o corte,
+o `olderThanDays`, o número do lote (`batch`) e os ids removidos, em blocos de no máximo 500 ids.
+No fim da execução que apagou algo, `opus.purge.total` traz `purged`, `batches` e `remaining`,
+verdadeiro quando a execução parou por tempo com o lote cheio ou foi interrompida por erro. Os
+registros vão para o `ctx.log` e, na falta dele, para o logger do runtime. Depois do expurgo, só
+eles e a auditoria da execução contam o que saiu.
+
 ### O que **não** entra
 
 - **ORM / Active Record.** Sem `deal.save()`, sem estado na instância. Entidade é descrição, não objeto vivo.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softize/opus",
-  "version": "24.0.1",
+  "version": "25.0.0",
   "description": "End-to-end action protocol for TypeScript. Single package with subpath exports (core + adapters).",
   "license": "MIT",
   "type": "module",

package/src/ai/drivers/anthropic.ts

@@ -13,6 +13,7 @@
  */
 
 import { zodToJsonSchema } from 'zod-to-json-schema'
+import { declaredJsonSchema } from '../../core/index.ts'
 import type {
   AiAdapter,
   AiCompleteOptions,
@@ -95,6 +96,8 @@ function sdk(): Promise<typeof import('@anthropic-ai/sdk')> {
 }
 
 function defaultToJsonSchema(schema: unknown): unknown {
+  const declared = declaredJsonSchema(schema)
+  if (declared !== null) return declared
   return zodToJsonSchema(schema as Parameters<typeof zodToJsonSchema>[0], { $refStrategy: 'none' })
 }