@softize/opus 24.1.0 → 25.0.0

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'