@softize/opus 24.1.0 → 25.1.0

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/docs/releasing.md

@@ -59,14 +59,20 @@ O token usado para publicar é exclusivamente o token do npm no `~/.npmrc` globa
 pra testar publicação seria a guarda atrapalhando quem está experimentando.
 
 **Gate de qualidade**: depois do bump e da materialização, mas antes de publicar, roda
-`pnpm typecheck` + `pnpm test` + `pnpm copy:check` + `base copy check` e **aborta a release
-se qualquer um falhar**. O Opus declara `@softize/base ^2.4.0` em `dependencies`, pois usa
+`pnpm typecheck` + `pnpm test` + `pnpm test:browser` + `pnpm copy:check` + `base copy check` e
+**aborta a release se qualquer um falhar**. O Opus declara `@softize/base ^2.4.0` em `dependencies`, pois usa
 suas APIs públicas de filesystem em runtime, e materializa os artefatos Base no próprio repo;
 a release não baixa uma política ad hoc. Como o
 Opus **ship source** (`.ts`, sem build), essa é a última barreira antes do tarball — sem ela,
 um `tsc` vermelho, inventário desatualizado ou violação da política vaza pro cliente. Emergência (evite):
 `pnpm release --skip-checks`.
 
+`pnpm test:browser` roda em Chromium real, pelo modo navegador do Vitest com Playwright, os testes
+que o `happy-dom` não reproduz com fidelidade, como o foco e o Tab da camada flutuante (ADR 0052).
+Ele fica fora do `pnpm test` para que o ciclo comum não dependa de navegador. O Chromium é o da
+revisão fixada pela versão exata do `playwright` nas devDependencies; se a estação não o tiver, o
+comando falha dizendo isso, e `pnpm exec playwright install chromium` o instala.
+
 O gate roda `pnpm test`, não `pnpm test:cov`: o threshold de 100% de cobertura em
 `vitest.config.ts` é uma meta aspiracional e **não** faz parte do gate de release. Uma release
 não é bloqueada por cobertura abaixo de 100%; a cobertura é acompanhada com `pnpm test:cov`.

package/docs/stacking-scale.md

@@ -0,0 +1,53 @@
+# Escala de empilhamento
+
+> **Status: decidido (out/2026).** As sobreposições do Opus ocupam quatro faixas de `z-index`,
+> definidas pela ADR 0052. Os valores são detalhe de implementação; a ordem entre as faixas é o
+> contrato.
+
+## Contexto
+
+Até a camada flutuante, toda sobreposição do Opus usava `z-50`: véu e conteúdo de Dialog e Drawer,
+Popover, Menu e Tooltip. A ordem no DOM desempatava, e o que abria depois ficava por cima. Isso
+bastava enquanto só existiam modais e sobreposições presas a um gatilho.
+
+A camada flutuante (`FloatingLayer`) precisa ficar acima de Dialog e Drawer e, ao mesmo tempo,
+abaixo dos diálogos de resposta obrigatória, que a cobrem com o véu (decisão 4 da seção 9 da ADR
+0052). A ordem no DOM não garante isso: o hospedeiro da camada é montado uma vez e continua no
+`body` enquanto modais abrem e fecham depois dele.
+
+## Decisão
+
+Do fundo para a frente:
+
+| Faixa                     | `z-index`     | Quem ocupa                                                                                     |
+| ------------------------- | ------------- | ---------------------------------------------------------------------------------------------- |
+| Conteúdo                  | `auto`        | A página.                                                                                      |
+| Modal                     | `50`          | Dialog, Drawer, seus véus e Popover, Menu e Tooltip abertos fora da camada.                    |
+| Camada flutuante          | `60`          | O hospedeiro `div[data-slot="floating-layer"]`.                                                |
+| Resposta obrigatória      | `70`          | Véu e conteúdo de `Dialog mode="alert"`, que também serve às confirmações do `DialogHost`.     |
+| Avisos                    | `999999999`   | O `Toaster`, com o valor do Sonner.                                                            |
+
+- Dentro de uma faixa, a ordem no DOM continua desempatando, como antes.
+- O hospedeiro da camada cria um contexto de empilhamento próprio. Popover, Menu, Tooltip, Dialog e
+  Drawer abertos de dentro dela são portados para o hospedeiro e mantêm o `z-50` lá dentro, acima
+  do painel que os abriu.
+- Popover, Menu e Tooltip abertos de dentro de um alerta herdam a faixa do alerta (`z-70`); sem
+  isso, ficariam por baixo do véu que o próprio alerta desenha.
+- Componente novo que abre uma sobreposição usa as faixas acima e lê o contêiner da camada; o
+  teste `tests/architecture/floating-layer.test.ts` cobra o contêiner de todo portal.
+- Um alerta em animação de saída deixa de receber clique (`pointer-events: none`). Sem isso, o véu
+  dele, ainda em `z-70`, cobriria por cerca de 150 ms o Dialog que a resposta abre na faixa de
+  baixo.
+
+## Consequências
+
+- Um consumidor que posiciona elementos próprios com `z-index` acima de `50` passa a competir com a
+  camada. Use a camada para o que precisa ficar acima dos modais, em vez de subir o `z-index`.
+- Um elemento do consumidor com `z-index` entre `51` e `69` ficava acima de um alerta, que estava em
+  `z-50`, e agora fica abaixo dele.
+- Uma sobreposição de outra biblioteca que fixa `z-50` e é aberta de dentro de um alerta fica abaixo
+  do véu do alerta, porque não lê a faixa que os primitives do Opus herdam. Suba a faixa dela para
+  `z-70` ou troque-a por um primitive do Opus.
+- Mudar um valor exige mudar todos os pontos que dependem dele: `overlayClasses` e o conteúdo em
+  `dialog.tsx` e `drawer.tsx`, o hospedeiro em `floating-layer.tsx` e a faixa do alerta em
+  `modal-layers.ts`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softize/opus",
-  "version": "24.1.0",
+  "version": "25.1.0",
   "description": "End-to-end action protocol for TypeScript. Single package with subpath exports (core + adapters).",
   "license": "MIT",
   "type": "module",
@@ -362,6 +362,7 @@
     "@opentelemetry/api": "^1.9.1",
     "@opentelemetry/context-async-hooks": "^2.10.0",
     "@opentelemetry/sdk-trace-base": "^2.10.0",
+    "@tailwindcss/vite": "^4.3.2",
     "@tanstack/react-query": "^5.62.0",
     "@testing-library/dom": "^10.4.0",
     "@testing-library/react": "^16.1.0",
@@ -371,6 +372,7 @@
     "@types/pg": "^8.11.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
+    "@vitest/browser": "2.1.9",
     "@vitest/coverage-v8": "^2.1.0",
     "better-sqlite3": "^11.0.0",
     "bullmq": "^5.0.0",
@@ -381,9 +383,11 @@
     "node-cron": "^3.0.3",
     "pg": "^8.13.0",
     "pino": "^9.5.0",
+    "playwright": "1.62.1",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "react-hook-form": "^7.54.0",
+    "tailwindcss": "^4.3.2",
     "tsx": "^4.19.0",
     "vite": "^6.0.0",
     "vitest": "^2.1.0",
@@ -400,6 +404,7 @@
     "copy:check": "node ./bin/cli.mjs copy --check",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
+    "test:browser": "vitest run --config vitest.browser.config.ts",
     "test:watch": "vitest",
     "test:cov": "vitest run --coverage",
     "registry:up": "npx -y verdaccio --config ~/.config/verdaccio/config.yaml",

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' })
 }
 

package/src/core/domain.ts

@@ -9,8 +9,11 @@
  *
  * Validações em runtime (em `defineDomain`):
  *   - `name` é string não-vazia no formato `[a-z][a-zA-Z0-9_]*`.
- *   - Actions têm nomes únicos dentro do domínio (incluindo subdomains).
+ *   - Actions e schedules têm nomes únicos dentro do domínio (incluindo subdomains e as peças de
+ *     expurgo derivadas das entidades com retenção — ADR 0051).
  *   - Subdomains têm nomes únicos entre siblings.
+ *   - Uma entidade com retenção aparece em um só domínio da árvore, e cada `bindPurge` em `purges`
+ *     aponta para uma entidade com `retainDays` do próprio domínio.
  *
  * Warnings (em `Runtime.register`, via `collectDomainWarnings`):
  *   - Actions cujo `name` não casa com `<root>(\.<sub>)*\.<verb>` emitem
@@ -24,6 +27,16 @@
 import type { ActionContract } from './contracts.ts'
 import type { DataProductConfig } from './data-product.ts'
 import { error } from './errors.ts'
+import {
+  entityTableName,
+  purgeActionName,
+  purgeContract,
+  purgeSchedule,
+  softDeleteRetention,
+  type PurgeBinding,
+  type SoftDeleteEntity,
+  type SoftDeleteRetention,
+} from './retention.ts'
 import type { ActionDef, ReactionDef, ScheduleDef } from './types.ts'
 
 /* eslint-disable @typescript-eslint/no-explicit-any */
@@ -83,6 +96,13 @@ export interface DomainConfig {
   /** Schedules registrados no domínio. */
   schedules?: ScheduleDef[]
 
+  /**
+   * Handlers próprios de expurgo (`bindPurge`, server-only) das entidades com `retainDays` listadas
+   * em `entities` deste mesmo domínio. Sem um deles, o runtime usa o handler padrão do driver de
+   * dados (ADR 0051).
+   */
+  purges?: Array<PurgeBinding<any>>
+
   /** Subdomínios (recursivo). */
   subdomains?: DomainConfig[]
 }
@@ -95,6 +115,26 @@ export interface FlattenedDomain {
   reactions: Array<ReactionDef<any>>
   schedules: ScheduleDef[]
   dataProducts: DataProductConfig[]
+  /**
+   * O expurgo derivado de cada entidade com `retainDays` (ADR 0051). A action e o schedule também
+   * estão em `actions` e `schedules`; aqui ficam ligados à entidade e ao `bindPurge`, se houver,
+   * para o runtime anexar o handler.
+   */
+  purges: DerivedPurge[]
+}
+
+/** O expurgo que o `flattenDomain` deriva de uma entidade com retenção. */
+export interface DerivedPurge {
+  /** Caminho completo do domínio que lista a entidade, como `report.share`. */
+  domain: string
+  entity: SoftDeleteEntity
+  retention: SoftDeleteRetention
+  /** O contrato da action, sem handler — o mesmo objeto que está em `actions`. */
+  action: ActionDef
+  /** A rotina diária — o mesmo objeto que está em `schedules`. */
+  schedule: ScheduleDef
+  /** O handler próprio, quando o domínio registrou um `bindPurge` para a entidade. */
+  binding?: PurgeBinding<any>
 }
 
 // =============================================================================
@@ -156,6 +196,7 @@ export function isDomainConfig(value: unknown): value is DomainConfig {
     'dicts' in v ||
     'entities' in v ||
     'dataProducts' in v ||
+    'purges' in v ||
     'repository' in v ||
     'service' in v
   )
@@ -166,8 +207,33 @@ export function isDomainConfig(value: unknown): value is DomainConfig {
  * pro `Runtime.register`.
  */
 export function flattenDomain(domain: DomainConfig): FlattenedDomain {
-  const out: FlattenedDomain = { actions: [], reactions: [], schedules: [], dataProducts: [] }
-  collect(domain, out)
+  const out = emptyFlattened()
+  collect(domain, out, [])
+  return out
+}
+
+/**
+ * O expurgo derivado das entidades com `retainDays` de UM nível do domínio, sem descer aos
+ * subdomínios. `parentPath` é a trilha dos ancestrais, que entra no nome da action. Puro e isomorfo,
+ * como o `flattenDomain`; o gerador do manifest o usa para projetar cada domínio no seu nível.
+ */
+export function domainPurges(domain: DomainConfig, parentPath: readonly string[] = []): DerivedPurge[] {
+  const path = [...parentPath, domain.name]
+  const out: DerivedPurge[] = []
+  for (const entity of retainedEntities(domain)) {
+    const retention = softDeleteRetention(entity) as SoftDeleteRetention
+    const name = purgeActionName(path, entity.name)
+    const binding = (domain.purges ?? []).find((item) => item?.entity === entity)
+    out.push({
+      domain: path.join('.'),
+      entity,
+      retention,
+      // Contrato puro: o runtime anexa o handler no `register` (ADR 0051).
+      action: purgeContract(name, retention) as unknown as ActionDef,
+      schedule: purgeSchedule(name, retention),
+      ...(binding !== undefined ? { binding } : {}),
+    })
+  }
   return out
 }
 
@@ -175,7 +241,11 @@ export function flattenDomain(domain: DomainConfig): FlattenedDomain {
 // Internos
 // =============================================================================
 
-function collect(domain: DomainConfig, out: FlattenedDomain): void {
+function emptyFlattened(): FlattenedDomain {
+  return { actions: [], reactions: [], schedules: [], dataProducts: [], purges: [] }
+}
+
+function collect(domain: DomainConfig, out: FlattenedDomain, parentPath: readonly string[]): void {
   for (const action of iterateActions(domain.actions)) {
     out.actions.push(action)
   }
@@ -185,6 +255,11 @@ function collect(domain: DomainConfig, out: FlattenedDomain): void {
   if (domain.schedules !== undefined) {
     for (const schedule of domain.schedules) out.schedules.push(schedule)
   }
+  for (const purge of domainPurges(domain, parentPath)) {
+    out.actions.push(purge.action)
+    out.schedules.push(purge.schedule)
+    out.purges.push(purge)
+  }
   if (domain.dataProducts !== undefined) {
     const products = Array.isArray(domain.dataProducts)
       ? domain.dataProducts
@@ -192,10 +267,29 @@ function collect(domain: DomainConfig, out: FlattenedDomain): void {
     for (const product of products) out.dataProducts.push(product)
   }
   if (domain.subdomains !== undefined) {
-    for (const sub of domain.subdomains) collect(sub, out)
+    const path = [...parentPath, domain.name]
+    for (const sub of domain.subdomains) collect(sub, out, path)
   }
 }
 
+/** Entidades de `entities` com `retainDays`, sem repetir a mesma referência. */
+function retainedEntities(domain: DomainConfig): SoftDeleteEntity[] {
+  const out: SoftDeleteEntity[] = []
+  for (const raw of Object.values(domain.entities ?? {})) {
+    if (!isNamedEntity(raw) || softDeleteRetention(raw) === null) continue
+    if (!out.includes(raw)) out.push(raw)
+  }
+  return out
+}
+
+function isNamedEntity(value: unknown): value is SoftDeleteEntity {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof (value as { name?: unknown }).name === 'string'
+  )
+}
+
 /**
  * Normaliza `actions` (record | array | record-of-array) em iterável plano
  * de `ActionDef`.
@@ -269,8 +363,11 @@ function validateDomain(domain: DomainConfig, path: string[]): void {
   // — actions: nomes únicos no domínio (e subdomínios) —
   // (Roda *depois* dos subdomains: assim erros de nome em subs aparecem
   // primeiro, antes de detectar duplicatas cruzadas.)
-  const collected: FlattenedDomain = { actions: [], reactions: [], schedules: [], dataProducts: [] }
-  collect(domain, collected)
+  assertRetainedEntitiesOnce(domain, path)
+  assertPurgeBindings(domain, fullPathStr)
+
+  const collected = emptyFlattened()
+  collect(domain, collected, path)
 
   const actionNames = new Set<string>()
   for (const action of collected.actions) {
@@ -284,6 +381,18 @@ function validateDomain(domain: DomainConfig, path: string[]): void {
     actionNames.add(action.name)
   }
 
+  const scheduleNames = new Set<string>()
+  for (const schedule of collected.schedules) {
+    if (scheduleNames.has(schedule.name)) {
+      throw error({
+        code: 'domain.duplicate_schedule',
+        category: 'internal',
+        message: `Schedule "${schedule.name}" duplicado em "${fullPathStr}"`,
+      })
+    }
+    scheduleNames.add(schedule.name)
+  }
+
   const entityNames = new Set<string>()
   const collectEntityNames = (current: DomainConfig): void => {
     for (const [key, raw] of Object.entries(current.entities ?? {})) {
@@ -327,6 +436,79 @@ function validateDomain(domain: DomainConfig, path: string[]): void {
   }
 }
 
+/**
+ * A action e a rotina do expurgo nascem no domínio que lista a entidade: a mesma entidade com
+ * retenção em dois pontos da árvore geraria dois expurgos da mesma tabela (ADR 0051). A comparação
+ * é pela tabela, para pegar também duas declarações `defineEntity` da mesma tabela.
+ */
+function assertRetainedEntitiesOnce(domain: DomainConfig, path: string[]): void {
+  const owners = new Map<string, string>()
+  const walk = (current: DomainConfig, parent: string[]): void => {
+    const here = [...parent, current.name].join('.')
+    const listed = Object.values(current.entities ?? {}).filter(
+      (raw): raw is SoftDeleteEntity => isNamedEntity(raw) && softDeleteRetention(raw) !== null,
+    )
+    for (const entity of listed) {
+      const table = entityTableName(entity)
+      const owner = owners.get(table)
+      if (owner !== undefined) {
+        throw entityRegisteredTwice(entity.name, table, owner, here)
+      }
+      owners.set(table, here)
+    }
+    for (const sub of current.subdomains ?? []) walk(sub, [...parent, current.name])
+  }
+  walk(domain, path)
+}
+
+/** Erro compartilhado com o `register`, que confere o mesmo entre domínios separados. */
+export function entityRegisteredTwice(
+  entity: string,
+  table: string,
+  first: string,
+  second: string,
+): ReturnType<typeof error> {
+  const where = first === second ? `duas vezes em "${first}"` : `em "${first}" e em "${second}"`
+  return error({
+    code: 'domain.entity_registered_twice',
+    category: 'internal',
+    message:
+      `A entidade "${entity}" (tabela "${table}") tem retenção e está registrada ${where}. O ` +
+      'expurgo nasce no domínio que lista a entidade em `entities`, e duas declarações da mesma ' +
+      'tabela gerariam dois expurgos dela; mantenha uma só entidade com retenção por tabela, num só domínio.',
+    meta: { entity, table, domains: [first, second] },
+  })
+}
+
+/** Cada `bindPurge` em `purges` aponta para uma entidade com `retainDays` do próprio domínio. */
+function assertPurgeBindings(domain: DomainConfig, domainPath: string): void {
+  const retained = retainedEntities(domain)
+  const listed = Object.values(domain.entities ?? {})
+  const bound = new Set<unknown>()
+  for (const binding of domain.purges ?? []) {
+    const entity = binding?.entity as SoftDeleteEntity | undefined
+    const name = typeof entity?.name === 'string' ? entity.name : '(sem nome)'
+    if (entity === undefined || !retained.includes(entity)) {
+      const reason = entity !== undefined && listed.includes(entity)
+        ? 'não declara `softDelete` com `retainDays`: sem prazo, não há expurgo para o handler executar'
+        : 'não está em `entities` deste domínio. Registre o bindPurge no domínio que lista a entidade'
+      throw error({
+        code: 'domain.invalid_purge',
+        category: 'internal',
+        message: `O bindPurge de "${name}" em "${domainPath}" aponta para uma entidade que ${reason}.`,
+      })
+    }
+    if (bound.has(entity)) {
+      throw error({
+        code: 'domain.duplicate_purge',
+        category: 'internal',
+        message: `A entidade "${name}" tem mais de um bindPurge em "${domainPath}".`,
+      })
+    }
+    bound.add(entity)
+  }
+}
+
 /**
  * Caminha a árvore emitindo warnings de nomenclatura. `path` é a trilha de
  * ancestrais (excluindo o próprio `domain`).

package/src/core/index.ts

@@ -198,8 +198,25 @@ export type { ReactionContract, ReactionBinding } from './reactions.ts'
 export { defineSchedule, isSchedule } from './schedules.ts'
 
 // — Domain ————————————————————————————————————————————————————————————————————
-export { defineDomain, flattenDomain, isDomainConfig } from './domain.ts'
-export type { DomainConfig, FlattenedDomain } from './domain.ts'
+export { defineDomain, domainPurges, flattenDomain, isDomainConfig } from './domain.ts'
+export type { DerivedPurge, DomainConfig, FlattenedDomain } from './domain.ts'
+
+// — Retenção da exclusão lógica (ADR 0051) ——————————————————————————————————————
+// `hasSoftDelete` mora em `@softize/opus/schema`, com a entidade; `bindPurge`, em
+// `@softize/opus/data`, porque o handler é server-only.
+export { declaredJsonSchema } from './retention.ts'
+export type {
+  PurgeBatchArgs,
+  PurgeBinding,
+  PurgeHandler,
+  PurgeInput,
+  PurgeOutput,
+  SoftDelete,
+  SoftDeleteForever,
+  SoftDeleteRetention,
+  SoftDeleteSchedule,
+  StandardJsonSchema,
+} from './retention.ts'
 
 // — Produtos de Dados ————————————————————————————————————————————————————————
 export { defineDataProduct, isDataProduct } from './data-product.ts'