@softize/opus 24.1.0 → 25.1.0

package/src/core/retention.ts

@@ -0,0 +1,493 @@
+/**
+ * Opus — retenção e expurgo da exclusão lógica (ADR 0051).
+ *
+ * Uma entidade com `softDelete` declara por quanto tempo guarda o registro excluído
+ * (`retainDays`) ou, com motivo, que guarda para sempre. Para cada entidade com prazo, o
+ * `flattenDomain` deriva um contrato de expurgo e a rotina diária que o executa; o runtime anexa o
+ * handler no servidor (padrão do driver de dados ou `bindPurge`) e repete os lotes até acabar ou
+ * esgotar o tempo.
+ *
+ * Este módulo é isomorfo: declara tipos, nomes e o contrato, e a repetição dos lotes, que não toca
+ * banco. O SQL do handler padrão mora no driver (`@softize/opus/data/kysely`). Não depende de zod,
+ * que é peer opcional: os schemas da action são Standard Schema escritos à mão, com o JSON Schema
+ * anexado para o manifest, o OpenAPI e o MCP.
+ */
+
+import type { SimpleContract } from './contracts.ts'
+import { error } from './errors.ts'
+import { isSystemActor } from './system-actor.ts'
+import type { ActionContext, HandlerFn, Logger, Schema, ScheduleDef, SchemaIssue } from './types.ts'
+
+// =============================================================================
+// Declaração na entidade
+// =============================================================================
+
+/** Rotina do expurgo: padrão `'30 3 * * *'`, habilitada. */
+export interface SoftDeleteSchedule {
+  cron?: string
+  enabled?: boolean
+}
+
+/** Exclusão lógica com prazo: o registro excluído sai de vez depois de `retainDays`. */
+export interface SoftDeleteRetention {
+  /** Inteiro positivo, até 3650; conta a partir de `deletedAt`. */
+  retainDays: number
+  /** Fuso IANA da rotina, obrigatório: o expurgo não depende do fuso da máquina. */
+  timezone: string
+  /** Título da action de expurgo, completo e literal: `'Expurgar relatórios excluídos'`. */
+  label: string
+  /** Descrição da action de expurgo, completa e literal. */
+  description: string
+  schedule?: SoftDeleteSchedule
+  /** Linhas por lote. Padrão 200. */
+  batchSize?: number
+  /** Tempo máximo de uma execução, em ms. Padrão 60.000. */
+  maxDurationMs?: number
+}
+
+/** Exclusão lógica sem expurgo: guarda o registro excluído para sempre, com o motivo. */
+export interface SoftDeleteForever {
+  retain: 'forever'
+  reason: string
+}
+
+/**
+ * Forma de `softDelete` numa entidade. `true` continua aceito pelo tipo, mas o `opus check`
+ * reprova: toda exclusão lógica declara a retenção ou o motivo para guardar (ADR 0051).
+ */
+export type SoftDelete = true | SoftDeleteRetention | SoftDeleteForever
+
+/** O recorte estrutural da entidade que o core lê. `EntityConfig` (schema) o satisfaz. */
+export interface SoftDeleteEntity {
+  name: string
+  table?: string
+  softDelete?: SoftDelete | false
+}
+
+/**
+ * Nome da tabela: `table` explícito ou plural simples de `name`. Mora no core para que a checagem
+ * de entidade repetida compare tabelas; `entityTable`, em `@softize/opus/schema`, delega para cá.
+ */
+export function entityTableName(entity: { name: string; table?: string }): string {
+  if (entity.table !== undefined) return entity.table
+  const n = entity.name
+  if (n.endsWith('y')) return `${n.slice(0, -1)}ies`
+  if (/(s|x|z|ch|sh)$/.test(n)) return `${n}es`
+  return `${n}s`
+}
+
+export const PURGE_DEFAULT_CRON = '30 3 * * *'
+export const PURGE_DEFAULT_BATCH_SIZE = 200
+/** Teto do `batchSize`: um lote maior pesa no banco e no registro de cada execução. */
+export const PURGE_MAX_BATCH_SIZE = 10_000
+/** Ids por registro `opus.purge`: um lote grande vira vários registros, nunca uma linha sem teto. */
+export const PURGE_LOG_IDS_PER_RECORD = 500
+export const PURGE_DEFAULT_MAX_DURATION_MS = 60_000
+/** Teto do `olderThanDays` aceito pela action, e portanto do `retainDays` declarado. */
+export const PURGE_MAX_OLDER_THAN_DAYS = 3650
+
+/**
+ * `true` quando a entidade faz exclusão lógica, em qualquer das três formas de `softDelete`. É o
+ * único ponto que decide a injeção de `deletedAt`, o filtro de leitura e a marcação no `remove`.
+ */
+export function hasSoftDelete(entity: { softDelete?: unknown }): boolean {
+  const value = entity.softDelete
+  return value === true || (typeof value === 'object' && value !== null)
+}
+
+/** A retenção com prazo da entidade, ou `null` quando não há prazo declarado. */
+export function softDeleteRetention(entity: { softDelete?: unknown }): SoftDeleteRetention | null {
+  const value = entity.softDelete
+  if (typeof value !== 'object' || value === null) return null
+  return 'retainDays' in value ? (value as SoftDeleteRetention) : null
+}
+
+/**
+ * Problemas da declaração de `softDelete`, em pt-BR, para o `defineEntity` recusar. Vazio quando a
+ * forma é válida. `true` não é problema aqui: o tipo o aceita e o `opus check` o reprova.
+ */
+export function softDeleteProblems(softDelete: unknown): string[] {
+  if (softDelete === undefined || softDelete === true || softDelete === false) return []
+  if (typeof softDelete !== 'object' || softDelete === null) {
+    return ['`softDelete` precisa ser `true`, um objeto com `retainDays` ou `{ retain: \'forever\', reason }`']
+  }
+  const value = softDelete as Record<string, unknown>
+  const hasDays = 'retainDays' in value
+  const hasForever = 'retain' in value
+  if (hasDays && hasForever) {
+    return ['`retainDays` e `retain: \'forever\'` são formas excludentes; declare só uma']
+  }
+  if (hasForever) {
+    const problems: string[] = []
+    if (value.retain !== 'forever') problems.push('`retain` só aceita `\'forever\'`')
+    if (!nonEmptyString(value.reason)) problems.push('`retain: \'forever\'` precisa de `reason` com o motivo')
+    return problems
+  }
+  if (!hasDays) {
+    return ['`softDelete` em objeto precisa de `retainDays` ou de `retain: \'forever\'` com `reason`']
+  }
+  const problems: string[] = []
+  const days = value.retainDays
+  if (typeof days !== 'number' || !Number.isInteger(days) || days < 1) {
+    problems.push('`retainDays` precisa ser um inteiro positivo')
+  } else if (days > PURGE_MAX_OLDER_THAN_DAYS) {
+    problems.push(`\`retainDays\` aceita no máximo ${PURGE_MAX_OLDER_THAN_DAYS} dias`)
+  }
+  if (!nonEmptyString(value.timezone)) problems.push('`timezone` é obrigatório (fuso IANA)')
+  else if (!validTimezone(value.timezone)) problems.push(`\`timezone\` "${value.timezone}" não é um fuso IANA válido`)
+  if (!nonEmptyString(value.label)) problems.push('`label` é obrigatório (título completo da action de expurgo)')
+  if (!nonEmptyString(value.description)) problems.push('`description` é obrigatória (descrição completa da action de expurgo)')
+  for (const key of ['batchSize', 'maxDurationMs'] as const) {
+    const n = value[key]
+    if (n !== undefined && (typeof n !== 'number' || !Number.isInteger(n) || n < 1)) {
+      problems.push(`\`${key}\` precisa ser um inteiro positivo`)
+    }
+  }
+  const batch = value.batchSize
+  if (typeof batch === 'number' && Number.isInteger(batch) && batch > PURGE_MAX_BATCH_SIZE) {
+    problems.push(`\`batchSize\` aceita no máximo ${PURGE_MAX_BATCH_SIZE} linhas por lote`)
+  }
+  const schedule = value.schedule
+  if (schedule !== undefined) {
+    if (typeof schedule !== 'object' || schedule === null) problems.push('`schedule` precisa ser um objeto')
+    else {
+      const { cron, enabled } = schedule as Record<string, unknown>
+      if (cron !== undefined && !nonEmptyString(cron)) problems.push('`schedule.cron` precisa ser uma expressão cron')
+      if (enabled !== undefined && typeof enabled !== 'boolean') problems.push('`schedule.enabled` precisa ser booleano')
+    }
+  }
+  return problems
+}
+
+function nonEmptyString(value: unknown): value is string {
+  return typeof value === 'string' && value.trim() !== ''
+}
+
+function validTimezone(timezone: string): boolean {
+  try {
+    new Intl.DateTimeFormat('en-US', { timeZone: timezone })
+    return true
+  } catch {
+    return false
+  }
+}
+
+// =============================================================================
+// Handler próprio (bindPurge)
+// =============================================================================
+
+/** O que o handler de um lote recebe: o contexto da execução, o corte e o tamanho do lote. */
+export interface PurgeBatchArgs {
+  ctx: ActionContext
+  /** Instante ISO: apaga somente registros com `deletedAt` anterior a ele. */
+  cutoff: string
+  batchSize: number
+}
+
+/**
+ * Apaga um lote de até `batchSize` registros com `deletedAt` anterior a `cutoff` e devolve os ids
+ * removidos; vazio quando acabou. Respeitar o `cutoff` é obrigação do handler: a garantia de nunca
+ * expurgar antes do prazo depende dele. Um id repetido na mesma execução, ou mais ids que
+ * `batchSize`, interrompe o expurgo com `purge.no_progress`.
+ */
+export type PurgeHandler = (args: PurgeBatchArgs) => Promise<{ ids: string[] }> | { ids: string[] }
+
+/**
+ * Handler próprio de expurgo, server-only, criado por `bindPurge` e registrado em `purges` no
+ * `defineDomain` que lista a entidade. O Opus continua dono do contrato, da rotina, dos lotes e do
+ * registro `opus.purge`.
+ */
+export interface PurgeBinding<E extends SoftDeleteEntity = SoftDeleteEntity> {
+  entity: E
+  handler: PurgeHandler
+}
+
+// =============================================================================
+// Nomes e contrato derivados
+// =============================================================================
+
+/** `reportShare` → `report-share`; `report_share` → `report-share`. */
+export function entityKebab(name: string): string {
+  return name
+    .replace(/_/g, '-')
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .toLowerCase()
+}
+
+/**
+ * `<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. O caminho entra como está.
+ */
+export function purgeActionName(domainPath: readonly string[], entityName: string): string {
+  const kebab = entityKebab(entityName)
+  const last = domainPath[domainPath.length - 1]
+  const segments = last === kebab ? [...domainPath] : [...domainPath, kebab]
+  return [...segments, 'purge-deleted'].join('.')
+}
+
+/** A rotina diária que dispara o expurgo: `<action>.daily`. */
+export function purgeScheduleName(actionName: string): string {
+  return `${actionName}.daily`
+}
+
+/** Entrada da action de expurgo, já com o padrão aplicado. */
+export interface PurgeInput {
+  olderThanDays: number
+}
+
+/** Saída da action de expurgo. */
+export interface PurgeOutput {
+  purged: number
+}
+
+/** JSON Schema anexado a um Standard Schema, no formato da extensão Standard JSON Schema. */
+export interface StandardJsonSchema {
+  input(options?: { target?: string }): Record<string, unknown>
+  output(options?: { target?: string }): Record<string, unknown>
+}
+
+/**
+ * JSON Schema declarado por um Standard Schema que o anexa em `~standard.jsonSchema`, ou `null`.
+ * O manifest, o OpenAPI e o MCP usam este caminho antes de recorrer ao zod.
+ */
+export function declaredJsonSchema(
+  schema: unknown,
+  options: { target?: string } = {},
+): Record<string, unknown> | null {
+  if (typeof schema !== 'object' || schema === null) return null
+  const standard = (schema as { '~standard'?: { jsonSchema?: Partial<StandardJsonSchema> } })['~standard']
+  const input = standard?.jsonSchema?.input
+  return typeof input === 'function' ? input(options) : null
+}
+
+type PurgeWireInput = { olderThanDays?: number }
+
+function standardSchema<In, Out>(
+  validate: (value: unknown) => { value: Out } | { issues: SchemaIssue[] },
+  jsonSchema: Record<string, unknown>,
+): Schema<In, Out> & { '~standard': { jsonSchema: StandardJsonSchema } } {
+  return {
+    '~standard': {
+      version: 1,
+      vendor: 'opus',
+      validate,
+      jsonSchema: {
+        input: () => structuredClone(jsonSchema),
+        output: () => structuredClone(jsonSchema),
+      },
+    },
+  }
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value)
+
+/** Entrada: `olderThanDays` inteiro entre `retainDays` e 3650, com `retainDays` como padrão. */
+function purgeInputSchema(days: number): Schema<PurgeWireInput, PurgeInput> {
+  return standardSchema<PurgeWireInput, PurgeInput>(
+    (value) => {
+      if (!isRecord(value)) {
+        return { issues: [{ message: 'Envie um objeto, vazio ou com `olderThanDays`.' }] }
+      }
+      const raw = value.olderThanDays
+      if (raw === undefined) return { value: { olderThanDays: days } }
+      const path = ['olderThanDays']
+      if (typeof raw !== 'number' || !Number.isInteger(raw)) {
+        return { issues: [{ message: 'Informe um número inteiro de dias.', path }] }
+      }
+      if (raw < days) {
+        return {
+          issues: [{ message: `O expurgo respeita a retenção declarada: informe pelo menos ${days} dias.`, path }],
+        }
+      }
+      if (raw > PURGE_MAX_OLDER_THAN_DAYS) {
+        return { issues: [{ message: `Informe no máximo ${PURGE_MAX_OLDER_THAN_DAYS} dias.`, path }] }
+      }
+      return { value: { olderThanDays: raw } }
+    },
+    {
+      type: 'object',
+      properties: {
+        olderThanDays: {
+          type: 'integer',
+          minimum: days,
+          maximum: PURGE_MAX_OLDER_THAN_DAYS,
+          default: days,
+        },
+      },
+      additionalProperties: false,
+    },
+  )
+}
+
+/** Saída: `{ purged }`, inteiro não negativo. */
+function purgeOutputSchema(): Schema<PurgeOutput> {
+  return standardSchema<PurgeOutput, PurgeOutput>(
+    (value) => {
+      const purged = isRecord(value) ? value.purged : undefined
+      if (typeof purged === 'number' && Number.isInteger(purged) && purged >= 0) {
+        return { value: { purged } }
+      }
+      return { issues: [{ message: '`purged` precisa ser um inteiro maior ou igual a zero.', path: ['purged'] }] }
+    },
+    {
+      type: 'object',
+      properties: { purged: { type: 'integer', minimum: 0 } },
+      required: ['purged'],
+      additionalProperties: false,
+    },
+  )
+}
+
+/**
+ * O contrato da action de expurgo, sem handler. Isomorfo: o manifest, o catálogo de design e o
+ * runtime leem o mesmo objeto.
+ */
+export function purgeContract(
+  actionName: string,
+  retention: SoftDeleteRetention,
+): SimpleContract<PurgeWireInput, PurgeOutput, PurgeInput> {
+  return {
+    name: actionName,
+    kind: 'simple',
+    // Literais da retenção: o Opus não monta frase a partir do nome do recurso, porque um modelo
+    // fixo erraria a concordância (ADR 0051).
+    label: retention.label,
+    description: retention.description,
+    input: purgeInputSchema(retention.retainDays),
+    output: purgeOutputSchema(),
+    effect: 'write',
+    personalData: false,
+    // Só o sistema executa o expurgo: a rotina diária roda como o sistema (ADR 0028), e não há
+    // execução manual por pessoa nesta decisão.
+    authorize: (ctx) => isSystemActor(ctx),
+    // Fora da IA: o expurgo é operação do sistema, irreversível e agendada, não pedido de uma
+    // pessoa numa conversa (ADR 0051).
+    ai: false,
+    automatable: true,
+    // Fora do REST: nenhuma rota HTTP dispara o expurgo; só o runtime, pela rotina.
+    internal: true,
+  }
+}
+
+/** A rotina diária do expurgo, no fuso declarado. Roda como o sistema (ADR 0028). */
+export function purgeSchedule(actionName: string, retention: SoftDeleteRetention): ScheduleDef {
+  return {
+    name: purgeScheduleName(actionName),
+    action: actionName,
+    cron: retention.schedule?.cron ?? PURGE_DEFAULT_CRON,
+    timezone: retention.timezone,
+    enabled: retention.schedule?.enabled ?? true,
+  }
+}
+
+// =============================================================================
+// Execução: lotes, tempo e registro
+// =============================================================================
+
+export interface PurgeRunSpec {
+  entity: string
+  action: string
+  retention: SoftDeleteRetention
+  /** Apaga um lote: o `bindPurge` do domínio ou o handler padrão do driver de dados. */
+  batch: PurgeHandler
+  /** Logger do runtime, usado quando o contexto não traz `log`. */
+  fallbackLog: Logger
+}
+
+/** Cede a vez ao event loop entre lotes, em Node e no navegador. */
+function yieldToEventLoop(): Promise<void> {
+  const immediate = (globalThis as { setImmediate?: (callback: () => void) => unknown }).setImmediate
+  return new Promise((resolve) => {
+    if (typeof immediate === 'function') immediate(resolve)
+    else setTimeout(resolve, 0)
+  })
+}
+
+/**
+ * Handler da action de expurgo: calcula o corte, repete os lotes enquanto houver ids e tempo, e
+ * registra o que saiu. Cada lote vira registros `opus.purge` com no máximo 500 ids; no fim, um
+ * registro `opus.purge.total` traz a quantidade e se restou trabalho. Um lote que repete um id ou
+ * excede o `batchSize` interrompe com `purge.no_progress`, depois de registrar os ids novos que ele
+ * trouxe; uma falha de lote interrompe com o erro original. Nos dois casos, o que já saiu fica
+ * registrado, com o total e `remaining: true`.
+ */
+export function createPurgeHandler(spec: PurgeRunSpec): HandlerFn<PurgeInput, PurgeOutput> {
+  const batchSize = spec.retention.batchSize ?? PURGE_DEFAULT_BATCH_SIZE
+  const maxDurationMs = spec.retention.maxDurationMs ?? PURGE_DEFAULT_MAX_DURATION_MS
+  return async (ctx, input) => {
+    const startedAt = Date.now()
+    const olderThanDays = input.olderThanDays
+    const cutoff = new Date(startedAt - olderThanDays * 86_400_000).toISOString()
+    const log = (ctx as Partial<ActionContext>).log ?? spec.fallbackLog
+    const base = { entity: spec.entity, action: spec.action, cutoff, olderThanDays }
+    const purged = new Set<string>()
+    let batches = 0
+    let remaining = false
+    const recordBatch = (ids: string[]): void => {
+      for (let start = 0; start < ids.length; start += PURGE_LOG_IDS_PER_RECORD) {
+        log.info('opus.purge', { ...base, batch: batches, ids: ids.slice(start, start + PURGE_LOG_IDS_PER_RECORD) })
+      }
+    }
+    const recordTotal = (): void => {
+      if (purged.size === 0) return
+      log.info('opus.purge.total', { ...base, purged: purged.size, batches, remaining })
+    }
+    const stop = (thrown: unknown): never => {
+      remaining = true
+      recordTotal()
+      throw thrown
+    }
+    for (;;) {
+      let removed: string[] = []
+      try {
+        removed = (await spec.batch({ ctx, cutoff, batchSize })).ids
+      } catch (thrown) {
+        // O lote que falhou não apagou nada; os anteriores, sim, e já estão registrados.
+        stop(thrown)
+      }
+      if (removed.length === 0) break
+      const repeated = removed.find((id) => purged.has(id))
+      const invalid =
+        removed.length > batchSize || repeated !== undefined || new Set(removed).size < removed.length
+      // Os ids novos do lote saem do banco mesmo quando o lote é inválido: entram no registro e no
+      // total antes da parada, porque os registros são o único rastro de uma exclusão irreversível.
+      const fresh = [...new Set(removed)].filter((id) => !purged.has(id))
+      if (fresh.length > 0) {
+        batches += 1
+        for (const id of fresh) purged.add(id)
+        recordBatch(fresh)
+      }
+      if (invalid) stop(noProgress(spec.entity, batchSize, removed.length, repeated))
+      if (Date.now() - startedAt >= maxDurationMs) {
+        remaining = removed.length >= batchSize
+        break
+      }
+      await yieldToEventLoop()
+    }
+    recordTotal()
+    return { purged: purged.size }
+  }
+}
+
+function noProgress(
+  entity: string,
+  batchSize: number,
+  returned: number,
+  repeated: string | undefined,
+): ReturnType<typeof error> {
+  const problem = returned > batchSize
+    ? `devolveu ${returned} ids num lote de ${batchSize}`
+    : repeated !== undefined
+      ? `devolveu de novo o id "${repeated}", já removido nesta execução`
+      : 'devolveu o mesmo id duas vezes no lote'
+  return error({
+    code: 'purge.no_progress',
+    category: 'internal',
+    message:
+      `O expurgo de "${entity}" parou porque o handler ${problem}. Sem essa parada, os lotes se ` +
+      'repetiriam sem avançar até o fim do tempo. Confira se o handler apaga os registros que devolve, ' +
+      'devolve cada id uma vez e respeita o `batchSize`.',
+    meta: { entity, batchSize, returned, ...(repeated !== undefined ? { repeated } : {}) },
+  })
+}

package/src/core/runtime.ts

@@ -14,13 +14,20 @@
 import { isReaction } from './reactions.ts'
 import { isBackgroundAction } from './actions.ts'
 import { isSchedule } from './schedules.ts'
-import { collectDomainWarnings, flattenDomain, isDomainConfig } from './domain.ts'
-import type { DomainConfig } from './domain.ts'
+import {
+  collectDomainWarnings,
+  entityRegisteredTwice,
+  flattenDomain,
+  isDomainConfig,
+} from './domain.ts'
+import type { DerivedPurge, DomainConfig } from './domain.ts'
+import { createPurgeHandler, entityTableName, type PurgeHandler } from './retention.ts'
 import type { DataProductConfig } from './data-product.ts'
 import { AuditEmitter } from './audit.ts'
 import { countReturnedRecords, hasInvalidEffect, resolveActionEffect } from './action-nature.ts'
 import { error, isActionError, normalizeError } from './errors.ts'
 import { normalizeTraceContext } from './trace.ts'
+import { isSystemActor, markSystemActor } from './system-actor.ts'
 import { evalExpression } from '../dsl/eval.ts'
 import { parseExpression } from '../dsl/parser.ts'
 import { parseLoad, resolveLoadArgs } from '../dsl/loads.ts'
@@ -318,6 +325,10 @@ export class Runtime {
   private readonly schedules = new Map<string, ScheduleDef>()
   private readonly dataProducts = new Map<string, DataProductConfig>()
   private readonly actionDataProducts = new Map<string, Set<string>>()
+  /** Tabela de entidade com retenção → domínio que a registrou; detecta o expurgo duplicado. */
+  private readonly retainedTables = new Map<string, string>()
+  /** Expurgos sem handler (sem `bindPurge` e sem driver de dados capaz): o `start()` recusa. */
+  private readonly purgesWithoutHandler: Array<{ entity: string; action: string }> = []
 
   /**
    * Map entidade → resolver, usado pra carregar specs DSL de loads
@@ -387,8 +398,15 @@ export class Runtime {
     for (const item of items) {
       if (isDomainConfig(item)) {
         collectDomainWarnings(item)
-        const { actions, reactions, schedules, dataProducts } = flattenDomain(item)
-        this.registerFlat(actions, reactions, schedules, dataProducts)
+        const { actions, reactions, schedules, dataProducts, purges } = flattenDomain(item)
+        this.claimRetainedEntities(purges)
+        const bound = new Map(purges.map((purge) => [purge.action, this.bindPurgeHandler(purge)]))
+        this.registerFlat(
+          actions.map((action) => bound.get(action) ?? action),
+          reactions,
+          schedules,
+          dataProducts,
+        )
       } else if (isSchedule(item)) {
         this.registerSchedules([item])
       } else if (isReaction(item)) {
@@ -424,6 +442,47 @@ export class Runtime {
     }
   }
 
+  /**
+   * A mesma entidade com retenção em dois domínios registrados separadamente geraria dois expurgos
+   * da mesma tabela. O `validateDomain` cobre a árvore de um domínio; aqui, o runtime inteiro.
+   */
+  private claimRetainedEntities(purges: DerivedPurge[]): void {
+    for (const purge of purges) {
+      const table = entityTableName(purge.entity)
+      const owner = this.retainedTables.get(table)
+      if (owner !== undefined) throw entityRegisteredTwice(purge.entity.name, table, owner, purge.domain)
+    }
+    for (const purge of purges) this.retainedTables.set(entityTableName(purge.entity), purge.domain)
+  }
+
+  /**
+   * Anexa o handler ao contrato de expurgo derivado (ADR 0051): o `bindPurge` do domínio ou, sem
+   * ele, o handler padrão do driver de dados. Sem nenhum dos dois, o contrato fica sem handler e o
+   * `start()` recusa com `runtime.purge_handler_missing`.
+   */
+  private bindPurgeHandler(purge: DerivedPurge): ActionDef {
+    const data = this.data
+    const batch: PurgeHandler | undefined =
+      purge.binding?.handler ??
+      (data?.purgeDeleted !== undefined
+        ? ({ cutoff, batchSize }) => data.purgeDeleted!(purge.entity, { cutoff, batchSize })
+        : undefined)
+    if (batch === undefined) {
+      this.purgesWithoutHandler.push({ entity: purge.entity.name, action: purge.action.name })
+      return purge.action
+    }
+    return {
+      ...purge.action,
+      handler: createPurgeHandler({
+        entity: purge.entity.name,
+        action: purge.action.name,
+        retention: purge.retention,
+        batch,
+        fallbackLog: this.log,
+      }),
+    } as ActionDef
+  }
+
   private registerFlat(
     actions: ActionDef[],
     reactions: Array<ReactionDef<any>>,
@@ -547,6 +606,10 @@ export class Runtime {
       })
     }
 
+    // Antes de inicializar adapters, como as conferências de schedule abaixo: um expurgo sem
+    // handler falharia em todo disparo da rotina.
+    this.assertPurgeHandlers()
+
     // Antes de inicializar adapters: é uma checagem do registro, e falhar aqui não deixa
     // conexão aberta para trás. Sem scheduler, a checagem não roda porque nenhum schedule
     // executaria: os adapters inicializam e o start falha depois, com
@@ -746,7 +809,7 @@ export class Runtime {
       ctxBase.trace,
       async (trace) => {
         const ctx = this.buildActionContext(action, actionId, ctxBase, trace)
-        if (system && ctx.user === null) systemContexts.add(ctx)
+        if (system) markSystemActor(ctx)
 
         try {
       // — 1. Validate input ————————————————————————————————————————————————
@@ -1364,6 +1427,28 @@ export class Runtime {
     })
   }
 
+  /**
+   * Uma entidade com `retainDays` cujo expurgo não tem quem apague: sem `bindPurge` no domínio e
+   * sem um `DataAdapter` que implemente o handler padrão (o driver Kysely). ADR 0051.
+   */
+  private assertPurgeHandlers(): void {
+    const missing = this.purgesWithoutHandler
+    if (missing.length === 0) return
+    const list = missing.map((item) => `"${item.entity}" (${item.action})`).join(', ')
+    throw error({
+      code: 'runtime.purge_handler_missing',
+      category: 'internal',
+      message:
+        `O runtime não iniciou porque ${
+          missing.length === 1
+            ? 'uma entidade com retenção não tem handler de expurgo'
+            : `${missing.length} entidades com retenção não têm handler de expurgo`
+        }: ${list}. Configure \`data\` com o driver Kysely (\`kyselyData\`), que traz o handler ` +
+        'padrão, ou registre um `bindPurge` em `purges` no domínio que lista a entidade.',
+      meta: { purges: missing.map((item) => ({ ...item })) },
+    })
+  }
+
   /**
    * Um schedule ativo cuja action não aceita o sistema falharia em todo disparo com
    * `auth.system_forbidden`. Como o `schedule_action_not_found`, o erro sai no boot, antes de
@@ -1805,30 +1890,9 @@ async function settledSuccessfully<T>(promise: Promise<T>): Promise<boolean> {
 // Identidade de sistema (ADR 0028)
 // =============================================================================
 
-/**
- * Contextos que o próprio runtime criou para uma execução do sistema. Um conjunto interno, e não
- * a provenance, decide `isSystemActor`: qualquer código servidor pode montar uma provenance
- * `schedule`, mas só o runtime acrescenta um contexto aqui.
- */
-const systemContexts = new WeakSet<object>()
-
-/**
- * Diz se a action está executando como o sistema: disparada por um schedule, ou no job que ele
- * enfileirou, sem usuário. Use no `authorize` de uma action `automatable` para aceitar o sistema
- * de forma explícita: `authorize: (ctx) => isSystemActor(ctx) || ctx.can('caixa:fechar')`.
- * Passe o próprio `ctx` recebido: uma cópia, como `{ ...ctx }`, não é reconhecida.
- */
-export function isSystemActor(ctx: ActionContext): boolean {
-  return systemContexts.has(ctx)
-}
-
-/**
- * Marca um contexto como execução do sistema. Exportado fora do index público, só para o harness
- * de `testing` aplicar a mesma regra no `runAction`.
- */
-export function markSystemActor(ctx: ActionContext): void {
-  if (ctx.user === null) systemContexts.add(ctx)
-}
+// `isSystemActor` e `markSystemActor` moram em `system-actor.ts`; o re-export mantém os caminhos
+// de import existentes (o harness de `testing` importa daqui).
+export { isSystemActor, markSystemActor }
 
 /**
  * O gate de autenticação do `execute` e do harness: sem usuário, a action precisa ser pública ou,