@softize/opus 24.1.0 → 25.1.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/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.