@softize/opus 24.1.0 → 25.1.0

package/CHANGELOG.md

@@ -7,6 +7,127 @@ Depois de qualquer bump, rode os gates (`typecheck` · `test` · `opus check` ·
 `opus copy --check` · `base copy check` · `manifest:check`) — eles apontam o que a
 mudança cobra do seu código.
 
+## 25.1.0 — 2026-10-03
+
+`FloatingLayer`, de `@softize/opus/ui/react`, é uma camada que continua utilizável por cima de
+qualquer `Dialog` ou `Drawer` modal, como o botão e o painel de um assistente (ADR 0052). Quem está
+preenchendo um formulário em um modal pode usar a camada sem fechar o modal nem perder o que digitou.
+Os filhos vão para um hospedeiro fixo no `body`, `div[data-slot="floating-layer"]`, e cada um se
+posiciona contra a janela. Com um `Dialog` ou `Drawer` aberto:
+
+- clicar na camada não fecha o modal, mesmo que o elemento clicado suma no próprio clique, e o véu
+  continua fechando, respeitando `closeDisabled`;
+- o foco pode ir para a camada por clique ou por código sem ser puxado de volta, e o Tab passa do
+  último elemento do modal para a camada e dela de volta ao primeiro; quando o elemento focado da
+  camada some, o foco volta ao campo do modal em que a pessoa estava, e um modal que fecha com a
+  pessoa na camada não leva o foco ao gatilho dele;
+- o Esc age onde a pessoa está: na camada, nenhum modal fecha e `onEscapeKeyDown` é chamado uma vez
+  por tecla; no modal, o modal fecha;
+- a camada rola e continua visível ao leitor de tela, enquanto a página atrás segue travada e
+  escondida.
+
+O hospedeiro publica o `Dialog` ou `Drawer` do topo em `data-modal` (`none`, `dialog` ou `drawer`) e o
+lado do Drawer em `data-modal-side`, para o consumidor tirar o painel de cima do modal. O Opus não
+desloca nem redimensiona modais. Os patterns construídos sobre `Dialog` e `Drawer`, como
+`ActionFormDialog`, `ActionListDialog`, `Presentation` e `CommandDialog`, convivem com a camada sem
+mudança.
+
+Outras mudanças:
+
+- Popover, Menu, Tooltip, Select, Dialog e Drawer abertos de dentro de uma `FloatingLayer` vão para o
+  hospedeiro dela, e não para o `body`; fora da camada, nada muda;
+- `Dialog mode="alert"`, que também serve às confirmações do `DialogHost`, passa à faixa `z-70`,
+  acima da camada (`z-60`) e dos demais modais (`z-50`), e cobre a camada até a resposta, inclusive
+  enquanto um `Dialog` aberto de dentro dele estiver aberto. Popover, Menu e Tooltip do Opus abertos
+  de dentro de um alerta acompanham a faixa dele. Dois efeitos para conferir no seu código: um
+  elemento próprio com `z-index` entre 51 e 69, que antes ficava acima do alerta, agora fica abaixo
+  dele; e uma sobreposição de outra biblioteca com `z-50`, aberta de dentro de um alerta, fica
+  abaixo do véu dele. Durante a animação de saída, o alerta deixa de receber clique. A escala está
+  em `docs/stacking-scale.md`;
+- `DialogPortal` e `MenuPortal` sem `container` usam o hospedeiro da camada quando abertos de
+  dentro dela;
+- a `ref` de `DialogContent` e `DrawerContent` continua recebendo a limpeza das callback refs do
+  React 19, agora composta com a ref interna da camada;
+- o pacote ganha testes em navegador real (Chromium, pelo modo navegador do Vitest com Playwright)
+  para o foco da camada: `pnpm test:browser` roda à parte do `pnpm test` e entra no gate de release.
+
+## 25.0.0 — 2026-10-02
+
+A exclusão lógica passa a declarar quando o registro excluído sai de vez (ADR 0051). `softDelete`
+aceita a retenção com prazo — `retainDays`, `timezone` e os textos `label` e `description` da action
+de expurgo, com `schedule`, `batchSize` e `maxDurationMs` opcionais — ou `{ retain: 'forever',
+reason }`. Para cada entidade com `retainDays`, o domínio que a lista em `entities` ganha a action
+`<caminho-do-domínio>.<entidade-em-kebab>.purge-deleted` e a rotina `<action>.daily`, que roda às
+3h30 no fuso declarado, como o sistema. A action aceita `olderThanDays` entre o `retainDays` e
+3650 e nunca expurga antes do prazo; só o sistema a executa, e ela fica fora do REST e da IA. Com
+`kyselyData`, o handler padrão apaga em lotes, das linhas mais antigas para as mais novas, até
+acabar ou esgotar `maxDurationMs`. Quando apagar a linha não basta, `bindPurge`, de
+`@softize/opus/data`, liga um handler próprio, registrado em `purges` no `defineDomain`; ele
+precisa respeitar o `cutoff` que recebe, e um lote que repete ids ou excede o `batchSize` interrompe
+o expurgo com `purge.no_progress`. Cada lote que apaga algo registra `opus.purge` no log, com os ids
+removidos em blocos de no máximo 500, e a execução termina com `opus.purge.total`, que traz a
+quantidade, os lotes e se restou trabalho. Os schemas da action gerada são Standard Schema com o
+JSON Schema anexado, sem zod: `@softize/opus` continua carregando sem zod instalado, e o manifest, o
+OpenAPI e o MCP leem esse JSON Schema antes de recorrer ao zod.
+
+Outras mudanças:
+
+- `hasSoftDelete(entity)`, de `@softize/opus/schema`, reconhece as três formas de `softDelete`.
+  `entityColumns`, o tipo `EntityRow` e o `kyselyRepo` passam por ela; um teste que comparava
+  `entity.softDelete === true` deve usá-la;
+- `defineEntity` recusa retenção inválida com `entity.invalid_soft_delete`: `retainDays` que não é
+  inteiro de 1 a 3650, `batchSize` acima de 10.000, fuso IANA inválido, texto vazio ou
+  `retain: 'forever'` sem `reason`;
+- `defineDomain` passa a recusar schedules com o mesmo nome na árvore (`domain.duplicate_schedule`),
+  como já fazia com actions; antes, o conflito só aparecia no `register`;
+- `FlattenedDomain` ganha `purges`, e `DataAdapter` ganha o método opcional `purgeDeleted`, que o
+  driver Kysely implementa;
+- `opus gen` projeta a action e a rotina de expurgo no manifest: rode-o para que o `manifest:check`
+  volte a passar;
+- `opus copy` lê o `label` e a `description` da retenção no `defineEntity`: rode-o para atualizar
+  o inventário;
+- `docs/protocol.md` deixa de prometer uma opção para incluir excluídos na leitura, que não existe.
+
+### Breaking
+
+**`softDelete: true` reprova no `opus check`.** A regra `soft-delete-retention` reprova a exclusão
+lógica sem retenção, `retain: 'forever'` sem `reason`, `retainDays` sem `timezone`, `label` ou
+`description` ou que não é inteiro positivo, `batchSize` acima de 10.000, entidade com `retainDays`
+fora de qualquer `entities` de domínio, `bindPurge` de entidade sem `retainDays` e `bindPurge` fora
+de qualquer `purges`.
+Migração: em cada `softDelete: true`, declare a retenção ou o motivo para guardar:
+
+```ts
+softDelete: {
+  retainDays: 90,
+  timezone: 'America/Sao_Paulo',
+  label: 'Expurgar relatórios excluídos',
+  description: 'Apaga de vez os relatórios excluídos há mais de 90 dias.',
+}
+// ou
+softDelete: { retain: 'forever', reason: 'Exigência legal de guarda do histórico.' }
+```
+
+Se o domínio já tem um expurgo escrito à mão, remova a action e o schedule próprios ao adotar
+`retainDays`: o nome gerado pode coincidir com o declarado (`domain.duplicate_action`). Para manter
+a ordem própria do que se apaga, mova o corpo para um `bindPurge`.
+
+**Entidade com `retainDays` exige quem apague e quem agende.** Sem `bindPurge` no domínio e sem um
+`DataAdapter` com o handler padrão (`kyselyData`), o `start()` recusa com
+`runtime.purge_handler_missing`, nomeando a entidade, antes de inicializar os adapters. Como toda
+rotina, a de expurgo exige um `SchedulerAdapter`; sem ele, o `start()` falha com
+`runtime.scheduler_required`. 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`, assim como duas declarações com
+retenção da mesma tabela. Migração: configure `data` e
+`scheduler` no runtime que registra o domínio, ou registre o `bindPurge`; mantenha cada entidade
+com retenção num único domínio.
+
+**Chave estrangeira restritiva para o expurgo.** O schema do Opus não declara cascata. Se uma chave
+estrangeira 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. Migração: antes de declarar `retainDays`, confira as chaves que
+apontam para a tabela; use cascata na DDL ou um `bindPurge` que apague os dependentes primeiro.
+
 ## 24.1.0 — 2026-10-02
 
 O `Markdown` deixa de carregar imagem com endereço absoluto (`https:`, `http:` ou `//host`). No

package/README.md

@@ -28,7 +28,7 @@ Um pacote (`@softize/opus`), uma versão. Cada categoria abaixo é um **subpath
 | `@softize/opus/server` | `/fastify`, `/node` | Transporte HTTP e montagem de endpoints |
 | `@softize/opus/client` | `/fetch` | Adapter de cliente para invocar actions |
 | `@softize/opus/ui` | `/react`, `/meta`, `/docs` | Componentes, Provider e hooks (`useAction`, `useListAction`) |
-| `@softize/opus/data` | `/kysely`, `/readonly-pool` | Adapter de dados (`ctx.db`, `ctx.repo`) |
+| `@softize/opus/data` | `/kysely`, `/readonly-pool` | Adapter de dados (`ctx.db`, `ctx.repo`) e expurgo próprio (`bindPurge`) |
 | `@softize/opus/auth` | `/jwt`, `/better-auth` | Adapter de autenticação (`ctx.user`, `ctx.can`) |
 | `@softize/opus/audit` | `/console`, `/pg` | Destinos de auditoria |
 | `@softize/opus/log` | `/pino` | Adapter de log (console é o default no core) |

package/bin/cli.mjs

@@ -446,6 +446,15 @@ Regras dos Produtos de Dados (defineDataProduct):
   data-product-*          — declaração exportada, id e versão válidos, sem duplicata,
                             interfaces e entidades que existem no domínio
 
+Regras da exclusão lógica (defineEntity, ADR 0051):
+  soft-delete-retention   — a exclusão lógica declara retenção ou motivo: reprova
+                            \`softDelete: true\`, \`retain: 'forever'\` sem \`reason\`,
+                            \`retainDays\` sem \`timezone\`, \`label\` ou \`description\`
+                            ou que não é inteiro positivo, \`batchSize\` acima de 10.000,
+                            entidade com \`retainDays\` fora de qualquer \`entities\` de
+                            domínio, \`bindPurge\` de entidade sem \`retainDays\` e
+                            \`bindPurge\` fora de \`purges\`
+
 Exit ≠ 0 se houver violação. Sem nenhuma action: projeto marcado (opus.json) passa
 vacuamente; sem marcador, falha — gate vazio não é aprovação. Default dir: cwd.
 `)

package/bin/lib/check.mjs

@@ -15,6 +15,15 @@
  *   ignored-by-kind        — `emits`/`background` em action list/view: o runtime e o manifest
  *                            só os aplicam em simple/form. No bindAction, o kind vem do
  *                            contrato pelo mesmo join por identificador exportado.
+ *   soft-delete-retention  — toda exclusão lógica declara retenção ou motivo para guardar
+ *                            (ADR 0051): reprova `softDelete: true`, `retain: 'forever'` sem
+ *                            `reason`, `retainDays` incompleto ou inválido, entidade com
+ *                            `retainDays` fora de qualquer `entities` de domínio, `bindPurge`
+ *                            de entidade sem `retainDays` e `bindPurge` fora de qualquer
+ *                            `purges`. A entidade e o `bindPurge` se ligam ao domínio pelo
+ *                            identificador exportado; um `entities` ou `purges` que o check não
+ *                            consegue ler (spread, variável) suspende a regra de ausência
+ *                            correspondente, sem falso positivo.
  *
  * A checagem cross-file de registro no runtime (graph) fica pra v2 (introspecção/MCP).
  * Saída: findings + exit ≠ 0 se houver erro. Zero actions num diretório NÃO-marcado
@@ -467,6 +476,377 @@ const UI_LEGACY_VARIANTS = new Map([
 /** Os três nomes que denotam action/contrato — o arquivo sem nenhum deles é pulado. */
 export const ACTION_MARKERS = ["defineAction", "defineContract", "bindAction"];
 export const DATA_PRODUCT_MARKERS = ["defineDataProduct", "defineEntity"];
+export const RETENTION_MARKERS = ["defineDomain", "bindPurge"];
+
+/** Teto do `retainDays`, o mesmo do `olderThanDays` da action de expurgo (src/core/retention.ts). */
+const MAX_RETAIN_DAYS = 3650;
+/** Teto do `batchSize` (PURGE_MAX_BATCH_SIZE em src/core/retention.ts). */
+const MAX_PURGE_BATCH_SIZE = 10000;
+
+/**
+ * Extrai a retenção das entidades, os `entities`/`purges` dos domínios e os `bindPurge` de um
+ * source (ADR 0051). Puro/sintático — a ligação entre arquivos fica no `checkProject`.
+ */
+export function parseRetention(fileName, sourceText) {
+  const sf = ts.createSourceFile(
+    fileName,
+    sourceText,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TS,
+  );
+  const entities = [];
+  const domains = [];
+  const purges = [];
+  const lineOf = (node) =>
+    sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1;
+  // `import { ReportEntity as Report }`: a referência no domínio usa o nome local; a ligação
+  // com a declaração precisa do nome exportado.
+  const aliases = new Map();
+  for (const statement of sf.statements) {
+    const bindings = ts.isImportDeclaration(statement)
+      ? statement.importClause?.namedBindings
+      : undefined;
+    if (bindings === undefined || !ts.isNamedImports(bindings)) continue;
+    for (const element of bindings.elements) {
+      if (element.propertyName !== undefined)
+        aliases.set(element.name.text, element.propertyName.text);
+    }
+  }
+  const refName = (node) => {
+    if (ts.isIdentifier(node)) return aliases.get(node.text) ?? node.text;
+    if (ts.isPropertyAccessExpression(node)) return node.name.text;
+    return null;
+  };
+  const isCallTo = (node, name) =>
+    ts.isCallExpression(node) &&
+    ts.isIdentifier(node.expression) &&
+    node.expression.text === name;
+  const prop = (obj, key) =>
+    obj.properties.find(
+      (item) =>
+        (ts.isPropertyAssignment(item) ||
+          ts.isShorthandPropertyAssignment(item)) &&
+        item.name?.getText(sf) === key,
+    );
+  const constIdent = (call) => {
+    const declaration = call.parent;
+    return declaration &&
+      ts.isVariableDeclaration(declaration) &&
+      ts.isIdentifier(declaration.name)
+      ? declaration.name.text
+      : null;
+  };
+  const isExported = (call) => {
+    const declaration = call.parent;
+    const statement =
+      declaration && ts.isVariableDeclaration(declaration)
+        ? declaration.parent?.parent
+        : undefined;
+    return (
+      statement !== undefined &&
+      ts.isVariableStatement(statement) &&
+      (statement.modifiers ?? []).some(
+        (item) => item.kind === ts.SyntaxKind.ExportKeyword,
+      )
+    );
+  };
+  const inlineEntities = new Set();
+  const inlinePurges = new Set();
+
+  /** Lê a forma de `softDelete` sem executar: literal reconhecido ou `opaque`. */
+  const softDeleteOf = (obj) => {
+    const entry = prop(obj, "softDelete");
+    if (entry === undefined) return { form: "none" };
+    if (!ts.isPropertyAssignment(entry)) return { form: "opaque" };
+    const value = entry.initializer;
+    if (value.kind === ts.SyntaxKind.TrueKeyword) return { form: "true" };
+    if (value.kind === ts.SyntaxKind.FalseKeyword) return { form: "none" };
+    if (!ts.isObjectLiteralExpression(value)) return { form: "opaque" };
+    const keys = new Set(
+      value.properties.map((item) => item.name?.getText(sf)).filter(Boolean),
+    );
+    // Um spread pode trazer qualquer chave: o que não está literal no objeto não é ausência.
+    const spread = value.properties.some(ts.isSpreadAssignment);
+    const literalText = (key) => {
+      const item = prop(value, key);
+      if (item === undefined) return undefined;
+      if (!ts.isPropertyAssignment(item)) return null;
+      const init = item.initializer;
+      return ts.isStringLiteral(init) || ts.isNoSubstitutionTemplateLiteral(init)
+        ? init.text
+        : null;
+    };
+    if (keys.has("retainDays")) {
+      const batchProp = prop(value, "batchSize");
+      const batchSize =
+        batchProp !== undefined &&
+        ts.isPropertyAssignment(batchProp) &&
+        ts.isNumericLiteral(batchProp.initializer)
+          ? Number(batchProp.initializer.text)
+          : null;
+      const days = prop(value, "retainDays");
+      let retainDays = null;
+      if (ts.isPropertyAssignment(days)) {
+        const init = days.initializer;
+        if (ts.isNumericLiteral(init)) retainDays = Number(init.text);
+        else if (
+          ts.isPrefixUnaryExpression(init) &&
+          init.operator === ts.SyntaxKind.MinusToken &&
+          ts.isNumericLiteral(init.operand)
+        )
+          retainDays = -Number(init.operand.text);
+        else if (ts.isStringLiteral(init)) retainDays = Number.NaN;
+      }
+      const missing = ["timezone", "label", "description"].filter((key) => {
+        if (!keys.has(key)) return !spread;
+        // Texto literal vazio conta como ausente; expressão não literal passa (o runtime confere).
+        return literalText(key) === "";
+      });
+      return {
+        form: "days",
+        retainDays,
+        batchSize,
+        missing,
+        conflicting: keys.has("retain"),
+      };
+    }
+    if (keys.has("retain")) {
+      // Expressão não literal (`null`) conta como presente; o runtime confere o valor.
+      const reason = literalText("reason");
+      return {
+        form: "forever",
+        reasonMissing:
+          (reason === undefined && !spread) ||
+          (typeof reason === "string" && reason.trim() === ""),
+      };
+    }
+    return { form: spread ? "opaque" : "invalid" };
+  };
+
+  /** `entities` e `purges` de um objeto de domínio (defineDomain ou subdomínio inline). */
+  const readDomain = (obj) => {
+    const domain = {
+      entityRefs: [],
+      entitiesOpaque: false,
+      purgeRefs: [],
+      purgesOpaque: false,
+      line: lineOf(obj),
+    };
+    const entitiesProp = prop(obj, "entities");
+    if (entitiesProp !== undefined) {
+      const value = ts.isPropertyAssignment(entitiesProp)
+        ? entitiesProp.initializer
+        : null;
+      if (value === null || !ts.isObjectLiteralExpression(value)) {
+        domain.entitiesOpaque = true;
+      } else {
+        for (const item of value.properties) {
+          if (ts.isShorthandPropertyAssignment(item)) {
+            domain.entityRefs.push(refName(item.name));
+          } else if (ts.isPropertyAssignment(item)) {
+            const init = item.initializer;
+            if (isCallTo(init, "defineEntity")) inlineEntities.add(init);
+            else {
+              const name = refName(init);
+              if (name === null) domain.entitiesOpaque = true;
+              else domain.entityRefs.push(name);
+            }
+          } else {
+            domain.entitiesOpaque = true;
+          }
+        }
+      }
+    }
+    const purgesProp = prop(obj, "purges");
+    if (purgesProp !== undefined) {
+      const value = ts.isPropertyAssignment(purgesProp)
+        ? purgesProp.initializer
+        : null;
+      if (value === null || !ts.isArrayLiteralExpression(value)) {
+        domain.purgesOpaque = true;
+      } else {
+        for (const element of value.elements) {
+          if (isCallTo(element, "bindPurge")) inlinePurges.add(element);
+          else {
+            const name = refName(element);
+            if (name === null) domain.purgesOpaque = true;
+            else domain.purgeRefs.push(name);
+          }
+        }
+      }
+    }
+    domains.push(domain);
+    const subdomains = prop(obj, "subdomains");
+    if (
+      subdomains !== undefined &&
+      ts.isPropertyAssignment(subdomains) &&
+      ts.isArrayLiteralExpression(subdomains.initializer)
+    ) {
+      // Subdomínio em `defineDomain(...)` é visitado como chamada própria; o literal, aqui.
+      for (const element of subdomains.initializer.elements) {
+        if (ts.isObjectLiteralExpression(element)) readDomain(element);
+      }
+    }
+  };
+
+  const entityCalls = [];
+  const purgeCalls = [];
+  const visit = (node) => {
+    if (
+      ts.isCallExpression(node) &&
+      ts.isIdentifier(node.expression) &&
+      node.arguments.length > 0
+    ) {
+      const callee = node.expression.text;
+      const first = node.arguments[0];
+      if (callee === "defineEntity" && ts.isObjectLiteralExpression(first))
+        entityCalls.push(node);
+      else if (callee === "defineDomain" && ts.isObjectLiteralExpression(first))
+        readDomain(first);
+      else if (callee === "bindPurge") purgeCalls.push(node);
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sf);
+
+  for (const call of entityCalls) {
+    const obj = call.arguments[0];
+    const nameProp = prop(obj, "name");
+    entities.push({
+      ident: constIdent(call),
+      name:
+        nameProp &&
+        ts.isPropertyAssignment(nameProp) &&
+        ts.isStringLiteral(nameProp.initializer)
+          ? nameProp.initializer.text
+          : null,
+      softDelete: softDeleteOf(obj),
+      inlineInDomain: inlineEntities.has(call),
+      line: lineOf(call),
+    });
+  }
+  for (const call of purgeCalls) {
+    purges.push({
+      ident: constIdent(call),
+      exported: isExported(call),
+      entityRef: refName(call.arguments[0]),
+      inlineInPurges: inlinePurges.has(call),
+      line: lineOf(call),
+    });
+  }
+  return { entities, domains, purges };
+}
+
+/**
+ * Regra `soft-delete-retention` (ADR 0051) sobre o projeto inteiro: a forma da declaração, por
+ * entidade, e a ligação entidade ↔ domínio ↔ `bindPurge`, pelo identificador exportado.
+ */
+function checkRetention(retention) {
+  const findings = [];
+  const finding = (file, line, subject, message) =>
+    findings.push({
+      rule: "soft-delete-retention",
+      level: "error",
+      action: subject,
+      line,
+      file,
+      message,
+    });
+  const domains = retention.flatMap(({ parsed }) => parsed.domains);
+  const entitiesOpaque = domains.some((domain) => domain.entitiesOpaque);
+  const purgesOpaque = domains.some((domain) => domain.purgesOpaque);
+  const entityRefs = new Set(domains.flatMap((domain) => domain.entityRefs));
+  const purgeRefs = new Set(domains.flatMap((domain) => domain.purgeRefs));
+  const entitiesByIdent = new Map(); // ident → entity | 'ambiguous'
+
+  for (const { file, parsed } of retention) {
+    for (const entity of parsed.entities) {
+      if (entity.ident !== null) {
+        entitiesByIdent.set(
+          entity.ident,
+          entitiesByIdent.has(entity.ident) ? "ambiguous" : entity,
+        );
+      }
+      const subject = entity.name ?? entity.ident ?? "(entidade sem name)";
+      const at = (message) => finding(file, entity.line, subject, message);
+      const { softDelete } = entity;
+      if (softDelete.form === "true") {
+        at(
+          "`softDelete: true` não declara por quanto tempo o registro excluído fica guardado. Declare `retainDays`, com `timezone`, `label` e `description`, ou `{ retain: 'forever', reason }`.",
+        );
+      } else if (softDelete.form === "invalid") {
+        at(
+          "`softDelete` em objeto precisa de `retainDays` ou de `retain: 'forever'` com `reason`.",
+        );
+      } else if (softDelete.form === "forever") {
+        if (softDelete.reasonMissing)
+          at(
+            "`retain: 'forever'` precisa de `reason` com o motivo de guardar o registro excluído para sempre.",
+          );
+      } else if (softDelete.form === "days") {
+        if (softDelete.conflicting)
+          at(
+            "`retainDays` e `retain: 'forever'` são formas excludentes; declare só uma.",
+          );
+        if (softDelete.missing.length > 0)
+          at(
+            `\`retainDays\` precisa de ${softDelete.missing.map((key) => `\`${key}\``).join(", ")}: o fuso da rotina e os textos completos da action de expurgo.`,
+          );
+        const days = softDelete.retainDays;
+        if (days !== null && (!Number.isInteger(days) || days < 1))
+          at("`retainDays` precisa ser um inteiro positivo.");
+        else if (days !== null && days > MAX_RETAIN_DAYS)
+          at(`\`retainDays\` aceita no máximo ${MAX_RETAIN_DAYS} dias.`);
+        const batch = softDelete.batchSize;
+        if (batch !== null && (!Number.isInteger(batch) || batch < 1))
+          at("`batchSize` precisa ser um inteiro positivo.");
+        else if (batch !== null && batch > MAX_PURGE_BATCH_SIZE)
+          at(`\`batchSize\` aceita no máximo ${MAX_PURGE_BATCH_SIZE} linhas por lote.`);
+        const inDomain =
+          entity.inlineInDomain ||
+          (entity.ident !== null && entityRefs.has(entity.ident));
+        if (!inDomain && !entitiesOpaque)
+          at(
+            "Entidade com `retainDays` fora de qualquer `entities` de domínio: o expurgo nasce no domínio que lista a entidade. Registre-a em `entities` no `defineDomain`.",
+          );
+      }
+    }
+  }
+
+  for (const { file, parsed } of retention) {
+    for (const purge of parsed.purges) {
+      const subject = `bindPurge(${purge.entityRef ?? "?"})`;
+      const entity =
+        purge.entityRef === null ? undefined : entitiesByIdent.get(purge.entityRef);
+      if (
+        entity !== undefined &&
+        entity !== "ambiguous" &&
+        entity.softDelete.form !== "days" &&
+        entity.softDelete.form !== "opaque"
+      ) {
+        finding(
+          file,
+          purge.line,
+          subject,
+          "`bindPurge` para uma entidade sem `retainDays`: sem prazo, não há expurgo para o handler executar.",
+        );
+      }
+      const registered =
+        purge.inlineInPurges ||
+        (purge.ident !== null && purgeRefs.has(purge.ident));
+      if (!registered && !purgesOpaque) {
+        finding(
+          file,
+          purge.line,
+          subject,
+          "`bindPurge` fora de qualquer `purges` de domínio: o runtime usaria o handler padrão em silêncio. Registre-o em `purges` no `defineDomain` que lista a entidade.",
+        );
+      }
+    }
+  }
+  return findings;
+}
 
 /** Extrai Produtos de Dados e entities literais para validar a linhagem sem executar o app. */
 export function parseDataProducts(fileName, sourceText) {
@@ -745,6 +1125,7 @@ export function checkProject(sources) {
   const productDeclarations = [];
   const entityNames = new Set();
   const actionNames = new Set();
+  const retention = [];
   // Natureza da action (ADR 0041): declarações ausentes são contadas, não reprovadas, na minor.
   let missingEffect = 0;
   let missingPersonalData = 0;
@@ -754,6 +1135,12 @@ export function checkProject(sources) {
     for (const entity of declarations.entities) entityNames.add(entity);
     for (const product of declarations.products)
       productDeclarations.push({ product, file });
+    if (
+      ["defineEntity", ...RETENTION_MARKERS].some((marker) =>
+        text.includes(marker),
+      )
+    )
+      retention.push({ file, parsed: parseRetention(file, text) });
     for (const item of parseActions(file, text)) {
       if (item.form === "bindAction") {
         actions += 1;
@@ -878,6 +1265,8 @@ export function checkProject(sources) {
     }
   }
 
+  findings.push(...checkRetention(retention));
+
   return {
     actions,
     contracts,
@@ -2147,7 +2536,7 @@ export async function scanDir(rootDir) {
   for (const file of files) {
     const text = readProjectFile(rootDir, path.relative(rootDir, file)).content;
     if (
-      ![...ACTION_MARKERS, ...DATA_PRODUCT_MARKERS].some((m) =>
+      ![...ACTION_MARKERS, ...DATA_PRODUCT_MARKERS, ...RETENTION_MARKERS].some((m) =>
         text.includes(m),
       )
     )

package/bin/lib/copy.mjs

@@ -1,7 +1,8 @@
 /**
  * Inventário semântico de copy dos contratos e dicionários Opus.
  *
- * O Opus conhece o papel dos textos declarados em defineAction/defineContract e t.dict;
+ * O Opus conhece o papel dos textos declarados em defineAction/defineContract, t.dict e na
+ * retenção de defineEntity (o `label` e a `description` da action de expurgo derivada);
  * a @softize/base continua dona da política e da validação editorial. Este módulo
  * apenas projeta o protocolo JSON v2 sem executar código do consumidor.
  */
@@ -78,6 +79,8 @@ const AUDIT_REFERENCE =
   /^(?:https?:\/\/\S+|[a-z][a-z0-9-]*:\S+|(?:[A-Za-z0-9._-]+\/)+[A-Za-z0-9._#/-]+|[A-Za-z0-9._-]+\.(?:md|json|ya?ml)(?:#[^\s]+)?)$/u
 const CONTRACT_MODULES = new Set(['@softize/opus', '@softize/opus/core'])
 const CONTRACT_FACTORIES = new Set(['defineAction', 'defineContract'])
+// A retenção da exclusão lógica declara os textos da action de expurgo que o Opus deriva (ADR 0051).
+const ENTITY_MODULES = new Set(['@softize/opus/schema'])
 const PRESENTATION_MODULES = new Set(['@softize/opus', '@softize/opus/presentation'])
 const SCHEMA_ZOD_MODULES = new Set(['@softize/opus/schema/zod'])
 const ACTION_BINDING_KEYS = new Set(['authorize', 'background', 'emits', 'handler', 'idempotency', 'loads'])
@@ -1407,6 +1410,7 @@ export function extractCopyFromSource(file, sourceText) {
   let hasContract = false
   let hasDictionary = false
   let hasPresentation = false
+  let hasEntity = false
   const hasUiImport = sourceFile.statements.some(
     (statement) =>
       ts.isImportDeclaration(statement) &&
@@ -1599,6 +1603,33 @@ export function extractCopyFromSource(file, sourceText) {
     return name !== null && CONTRACT_FACTORIES.has(name) ? name : null
   }
 
+  function entityFactory(expression) {
+    return importedMember(expression, (module) => ENTITY_MODULES.has(module)) === 'defineEntity'
+  }
+
+  /**
+   * `softDelete` com `retainDays` traz o título e a descrição, completos e literais, da action de
+   * expurgo que o `flattenDomain` deriva (ADR 0051). `true`, `false` e `retain: 'forever'` não
+   * têm texto para pessoas.
+   */
+  function extractEntity(object) {
+    const resolved = property(object, 'softDelete', sourceFile, checker)
+    if (resolved.opaque !== undefined) {
+      diagnostics.push(diagnostic(file, sourceFile, resolved.opaque, 'softDelete', 'structure'))
+      return
+    }
+    if (resolved.candidate === undefined) return
+    const valueNode = propertyValue(resolved.candidate)
+    const value = resolveBinding(valueNode, checker)
+    if (value.kind === ts.SyntaxKind.TrueKeyword || value.kind === ts.SyntaxKind.FalseKeyword) return
+    if (!ts.isObjectLiteralExpression(value)) {
+      diagnostics.push(diagnostic(file, sourceFile, valueNode, 'softDelete', 'structure'))
+      return
+    }
+    addProperty(value, 'label', 'button', 'softDelete.')
+    addProperty(value, 'description', 'description', 'softDelete.')
+  }
+
   function presentationFactory(expression) {
     return importedMember(expression, (module) => PRESENTATION_MODULES.has(module)) === 'definePresentation'
   }
@@ -2582,6 +2613,12 @@ export function extractCopyFromSource(file, sourceText) {
         else diagnostics.push(diagnostic(file, sourceFile, node.arguments[0], `${factory}(...)`, 'structure'))
       }
     }
+    if (ts.isCallExpression(node) && entityFactory(node.expression) && node.arguments.length > 0) {
+      hasEntity = true
+      const object = resolveBinding(node.arguments[0], checker)
+      if (ts.isObjectLiteralExpression(object)) extractEntity(object)
+      else diagnostics.push(diagnostic(file, sourceFile, node.arguments[0], 'defineEntity(...)', 'structure'))
+    }
     if (ts.isCallExpression(node) && presentationFactory(node.expression) && node.arguments.length > 0) {
       hasPresentation = true
       const object = resolveBinding(node.arguments[0], checker)
@@ -2599,7 +2636,7 @@ export function extractCopyFromSource(file, sourceText) {
 
   return {
     hasContract,
-    hasCopySurface: hasContract || hasDictionary || hasPresentation || hasUiImport,
+    hasCopySurface: hasContract || hasDictionary || hasPresentation || hasEntity || hasUiImport,
     entries,
     diagnostics,
   }