@softize/opus 24.1.0 → 25.0.0

package/src/core/system-actor.ts

@@ -0,0 +1,33 @@
+/**
+ * Opus — identidade de sistema (ADR 0028).
+ *
+ * Mora fora do `runtime.ts` para que declarações puras do core, como o contrato de expurgo que o
+ * `flattenDomain` deriva (ADR 0051), possam usar `isSystemActor` sem importar o runtime.
+ */
+
+import type { ActionContext } from './types.ts'
+
+/**
+ * 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 runtime e
+ * o harness de `testing` aplicarem a mesma regra.
+ */
+export function markSystemActor(ctx: ActionContext): void {
+  if (ctx.user === null) systemContexts.add(ctx)
+}

package/src/core/types.ts

@@ -21,6 +21,8 @@
  *  13. RuntimeConfig (§14)
  */
 
+import type { SoftDeleteEntity } from './retention.ts'
+
 // =============================================================================
 // 1. Primitivos & shared
 // =============================================================================
@@ -1156,6 +1158,16 @@ export interface ServerAdapter extends Adapter {
 export interface DataAdapter extends Adapter {
   kind: 'data'
   contextExtension(): { db: unknown }
+  /**
+   * Apaga um lote de até `batchSize` linhas excluídas logicamente com `deletedAt` anterior a
+   * `cutoff`, das mais antigas para as mais novas, e devolve os ids removidos. É o handler padrão
+   * do expurgo (ADR 0051): o driver Kysely o implementa. Com um adapter sem este método, cada
+   * entidade com `retainDays` precisa de `bindPurge`, senão o `start()` recusa.
+   */
+  purgeDeleted?(
+    entity: SoftDeleteEntity,
+    options: { cutoff: string; batchSize: number },
+  ): Promise<{ ids: string[] }>
 }
 
 export interface AuthAdapter extends Adapter {

package/src/data/drivers/kysely.ts

@@ -29,6 +29,7 @@ import { defineAction, error, type ActionDef, type AuthorizeFn } from '../../cor
 import type { DataAdapter, HealthStatus, Paginated } from '../../core/index.ts'
 import {
   desiredColumns,
+  hasSoftDelete,
   diffColumns,
   entityTable,
   entityPk,
@@ -81,9 +82,50 @@ export function kyselyData<DB>(options: KyselyDataOptions<DB>): DataAdapter {
     async dispose() {
       await db.destroy()
     },
+
+    // Handler padrão do expurgo (ADR 0051): o runtime o usa para toda entidade com `retainDays`
+    // sem `bindPurge` no domínio.
+    async purgeDeleted(entity, options) {
+      return purgeDeletedBatch(db as Kysely<unknown>, entity as EntityConfig, options)
+    },
   }
 }
 
+/**
+ * Apaga um lote de linhas excluídas antes do corte, das mais antigas para as mais novas. A exclusão
+ * é uma instrução só: se uma chave estrangeira restritiva recusar uma linha, o banco recusa o lote
+ * inteiro e nada dele sai. A coluna segue o mesmo nome que o `kyselyRepo` usa (`deletedAt`).
+ */
+async function purgeDeletedBatch(
+  db: Kysely<unknown>,
+  entity: EntityConfig,
+  options: { cutoff: string; batchSize: number },
+): Promise<{ ids: string[] }> {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const qb = db as Kysely<any>
+  const table = entityTable(entity)
+  const pk = entityPk(entity).name
+  const candidates = await qb
+    .selectFrom(table)
+    .select(pk)
+    .where('deletedAt', 'is not', null)
+    .where('deletedAt', '<', options.cutoff)
+    .orderBy('deletedAt')
+    .orderBy(pk)
+    .limit(options.batchSize)
+    .execute()
+  if (candidates.length === 0) return { ids: [] }
+  const keys = candidates.map((row) => row[pk] as unknown)
+  const deleted = await qb
+    .deleteFrom(table)
+    .where(pk, 'in', keys)
+    .where('deletedAt', '<', options.cutoff)
+    .returning(pk)
+    .execute()
+  const removed = new Set(deleted.map((row) => String(row[pk])))
+  return { ids: keys.map(String).filter((id) => removed.has(id)) }
+}
+
 function round(n: number): number {
   return Math.round(n * 100) / 100
 }
@@ -136,7 +178,7 @@ export function kyselyRepo<E extends EntityConfig>(
   const now = options.now ?? (() => new Date().toISOString())
   const genId = options.genId ?? (() => randomUUID())
   const hasTimestamps = entity.timestamps === true
-  const hasSoftDelete = entity.softDelete === true
+  const softDelete = hasSoftDelete(entity)
   // Campos t.json(): o repo serializa NA ESCRITA (insert/update). Sem isso, o pg
   // até stringifica objeto plano sozinho — mas ARRAY vira literal de array PG
   // (errado pra jsonb) sem quebrar typecheck. A declaração já sabe o tipo; a
@@ -175,7 +217,7 @@ export function kyselyRepo<E extends EntityConfig>(
 
     async findById(id) {
       let q = qb.selectFrom(table).selectAll().where(pk.name, '=', id)
-      if (hasSoftDelete) q = q.where('deletedAt', 'is', null)
+      if (softDelete) q = q.where('deletedAt', 'is', null)
       const found = await q.executeTakeFirst()
       return (found ?? null) as EntityRow<E> | null
     },
@@ -193,7 +235,7 @@ export function kyselyRepo<E extends EntityConfig>(
     },
 
     async remove(id) {
-      if (hasSoftDelete) {
+      if (softDelete) {
         await qb.updateTable(table).set({ deletedAt: now() }).where(pk.name, '=', id).execute()
         return
       }
@@ -202,7 +244,7 @@ export function kyselyRepo<E extends EntityConfig>(
 
     async all() {
       let q = qb.selectFrom(table).selectAll()
-      if (hasSoftDelete) q = q.where('deletedAt', 'is', null)
+      if (softDelete) q = q.where('deletedAt', 'is', null)
       const rows = await q.execute()
       return rows as EntityRow<E>[]
     },
@@ -211,7 +253,7 @@ export function kyselyRepo<E extends EntityConfig>(
       const limit = params.limit ?? 50
       const offset = params.offset ?? 0
       const applyFilters = (query: any): any => {
-        let out = hasSoftDelete ? query.where('deletedAt', 'is', null) : query
+        let out = softDelete ? query.where('deletedAt', 'is', null) : query
         if (params.where !== undefined) {
           for (const [col, value] of Object.entries(params.where)) {
             out = out.where(col, '=', value)

package/src/data/index.ts

@@ -1,10 +1,28 @@
 /**
- * @softize/opus/data — shared helpers/types for data drivers.
+ * @softize/opus/data — helpers e tipos compartilhados da camada de dados, server-only.
  *
- * Empty for now — drivers (kysely, drizzle) são thin wrappers que apenas
- * implementam o contrato `DataAdapter` do core. Quando aparecer código
- * compartilhado (helpers de transação, observability hooks, etc),
- * mora aqui.
+ * Os drivers (kysely) implementam o contrato `DataAdapter` do core. Aqui mora o que o domínio
+ * liga no servidor sobre os dados, como o handler próprio de expurgo (`bindPurge`, ADR 0051).
  */
 
-export {}
+import type { PurgeBinding, PurgeHandler, SoftDeleteEntity } from '../core/retention.ts'
+
+export type { PurgeBatchArgs, PurgeBinding, PurgeHandler } from '../core/retention.ts'
+
+/**
+ * Liga um handler próprio ao expurgo de uma entidade com `retainDays`, para quando apagar a linha
+ * não basta: levar junto registros dependentes, apagar dados em outro serviço ou preservar parte do
+ * histórico. Registre o resultado em `purges` no `defineDomain` que lista a entidade.
+ *
+ * O handler apaga um lote de até `batchSize` registros com `deletedAt` anterior a `cutoff` e
+ * devolve os ids removidos, cada um uma vez. Respeitar o `cutoff` é obrigação do handler: o Opus
+ * recusa um `olderThanDays` abaixo do `retainDays`, mas só o handler decide o que apaga, e 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`.
+ *
+ * O Opus continua dono do contrato, da rotina, da repetição dos lotes e do registro `opus.purge`;
+ * sem `bindPurge`, vale o handler padrão do driver Kysely.
+ */
+export function bindPurge<E extends SoftDeleteEntity>(entity: E, handler: PurgeHandler): PurgeBinding<E> {
+  return { entity, handler }
+}

package/src/mcp/index.ts

@@ -12,7 +12,7 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js'
 import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js'
 import { zodToJsonSchema } from 'zod-to-json-schema'
-import type { ContextBase, Runtime } from '../core/index.ts'
+import { declaredJsonSchema, type ContextBase, type Runtime } from '../core/index.ts'
 import { readPackageVersion } from '../core/package-version.ts'
 import { aiToolNotFound } from '../core/runtime.ts'
 
@@ -35,7 +35,8 @@ const ANON: ContextBase = { user: null, tenantId: null, can: () => false, meta:
  */
 export function createOpusMcpServer(runtime: Runtime, opts: OpusMcpOptions = {}): Server {
   const toJsonSchema =
-    opts.toJsonSchema ?? ((schema: unknown) => zodToJsonSchema(schema as never, { $refStrategy: 'none' }))
+    opts.toJsonSchema ??
+    ((schema: unknown) => declaredJsonSchema(schema) ?? zodToJsonSchema(schema as never, { $refStrategy: 'none' }))
 
   const server = new Server(
     { name: opts.name ?? 'opus', version: opts.version ?? readPackageVersion() },

package/src/schema/entity.ts

@@ -15,6 +15,14 @@
 
 import { z } from 'zod'
 import { error } from '../core/index.ts'
+import {
+  entityTableName,
+  hasSoftDelete,
+  softDeleteProblems,
+  type SoftDelete,
+  type SoftDeleteForever,
+  type SoftDeleteRetention,
+} from '../core/retention.ts'
 import type { ColumnMeta, LogicalType } from './drivers/zod.ts'
 
 /* eslint-disable @typescript-eslint/no-explicit-any */
@@ -90,10 +98,18 @@ export interface EntityConfig<F extends EntityFields = EntityFields> {
   indexes?: IndexSpec[]
   /** Injeta `createdAt`/`updatedAt` (geridos pelo runtime). */
   timestamps?: boolean
-  /** Injeta `deletedAt`; search/view filtram deletados por default. */
-  softDelete?: boolean
+  /**
+   * Exclusão lógica: injeta `deletedAt`, e o `kyselyRepo` filtra os excluídos e marca a data em
+   * vez de apagar. Declare a retenção — `retainDays`, com fuso e os textos da action de expurgo —
+   * ou `{ retain: 'forever', reason }`. `true` ainda é aceito pelo tipo, mas o `opus check` o
+   * reprova (ADR 0051).
+   */
+  softDelete?: SoftDelete | false
 }
 
+export { hasSoftDelete }
+export type { SoftDelete, SoftDeleteForever, SoftDeleteRetention }
+
 // =============================================================================
 // Inferência de tipos
 // =============================================================================
@@ -115,7 +131,7 @@ type IdPart<F> = HasPk<F> extends true ? {} : { id: string }
 type TimestampPart<E> = E extends { timestamps: true }
   ? { createdAt: string; updatedAt: string }
   : {}
-type SoftDeletePart<E> = E extends { softDelete: true } ? { deletedAt: string | null } : {}
+type SoftDeletePart<E> = E extends { softDelete: SoftDelete } ? { deletedAt: string | null } : {}
 
 /** Linha completa da entidade (id auto + campos + timestamps + softDelete). */
 export type EntityRow<E extends EntityConfig> = Simplify<
@@ -188,6 +204,15 @@ function validateEntity(config: EntityConfig): void {
     })
   }
 
+  const retentionProblems = softDeleteProblems(config.softDelete)
+  if (retentionProblems.length > 0) {
+    throw error({
+      code: 'entity.invalid_soft_delete',
+      category: 'internal',
+      message: `A retenção de "${config.name}" é inválida: ${retentionProblems.join('; ')}.`,
+    })
+  }
+
   if (config.relations !== undefined) {
     for (const [relName, rel] of Object.entries(config.relations)) {
       if (typeof rel.target !== 'string' || rel.target.length === 0) {
@@ -239,7 +264,7 @@ export function entityColumns(config: EntityConfig): ResolvedColumn[] {
     cols.push({ name: 'createdAt', logicalType: 'datetime', column: {}, generated: true })
     cols.push({ name: 'updatedAt', logicalType: 'datetime', column: {}, generated: true })
   }
-  if (config.softDelete === true) {
+  if (hasSoftDelete(config)) {
     cols.push({
       name: 'deletedAt',
       logicalType: 'datetime',
@@ -301,11 +326,7 @@ export function entityUpdateSchema(config: EntityConfig): z.ZodObject<z.ZodRawSh
 
 /** Nome da tabela: `table` explícito ou plural simples de `name`. */
 export function entityTable(config: EntityConfig): string {
-  if (config.table !== undefined) return config.table
-  const n = config.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`
+  return entityTableName(config)
 }
 
 /**

package/src/schema/index.ts

@@ -41,6 +41,7 @@ export {
   desiredColumns,
   diffColumns,
   isEntityConfig,
+  hasSoftDelete,
   snakeCase,
   resolveNaming,
 } from './entity.ts'
@@ -58,6 +59,9 @@ export type {
   DriftKind,
   DriftFinding,
   NamingStrategy,
+  SoftDelete,
+  SoftDeleteForever,
+  SoftDeleteRetention,
 } from './entity.ts'
 
 // — Scaffold de migration ——————————————————————————————————————————————————————

package/src/schema/openapi.ts

@@ -14,7 +14,7 @@
  * — apenas actions registradas viram operations OpenAPI.
  */
 
-import type { ActionDef, ErrorSpec } from '../core/index.ts'
+import { declaredJsonSchema, type ActionDef, type ErrorSpec } from '../core/index.ts'
 import { zodToJsonSchema } from 'zod-to-json-schema'
 
 // =============================================================================
@@ -119,6 +119,9 @@ export function toOpenAPISpec(
 // =============================================================================
 
 function defaultToJsonSchema(schema: unknown): unknown {
+  // Standard Schema que declara o próprio JSON Schema (como as actions de expurgo, ADR 0051).
+  const declared = declaredJsonSchema(schema, { target: 'openapi-3.0' })
+  if (declared !== null) return declared
   return zodToJsonSchema(schema as Parameters<typeof zodToJsonSchema>[0], {
     target: 'openApi3',
     $refStrategy: 'none',

package/src/ui/docs/content/cli.md

@@ -20,11 +20,13 @@ opus db check         # drift entidade ↔ banco (read-only)
 opus seed check       # bindings, dependências, ciclos e scripts paralelos de seed
 ```
 
-`opus check` lê o código-fonte sem executá-lo e aplica regras em três grupos: actions
+`opus check` lê o código-fonte sem executá-lo e aplica regras em quatro grupos: actions
 (`action-name`, `kind`, `field-order`, `export`, `requires-sem-authorize`, `ignored-by-kind`), UI
-(`ui-structure`, `ui-structure-split`, `ui-semantic-api`, `removed-ui-token`, `unpaired-ui-surface`) e
+(`ui-structure`, `ui-structure-split`, `ui-semantic-api`, `removed-ui-token`, `unpaired-ui-surface`),
 [Produtos de Dados](/docs/data-products) (`data-product-export`, `-id`, `-duplicate`, `-version`,
-`-interfaces`, `-interface`, `-entities` e `-entity`, todas com o prefixo `data-product`). Um projeto
+`-interfaces`, `-interface`, `-entities` e `-entity`, todas com o prefixo `data-product`) e
+[exclusão lógica](/docs/data) (`soft-delete-retention`, que cobra a retenção de cada entidade e a
+ligação com o domínio). Um projeto
 marcado com `opus.json` e ainda sem actions passa sem achados; sem o marcador, nenhuma action
 encontrada é falha, porque um gate que não verificou nada não é aprovação. `opus check --help` descreve cada regra.
 

package/src/ui/docs/content/data.md

@@ -30,6 +30,48 @@ export const SkillEntity = defineEntity({
 })
 ```
 
+## Exclusão lógica e expurgo
+
+Use `softDelete` quando um registro excluído precisa continuar no banco por um tempo, como
+histórico ou para atender uma regra de guarda. `kyselyRepo` passa a marcar `deletedAt` em
+`remove`, e `findById`, `all` e `list` deixam os excluídos de fora.
+
+A declaração também diz quando o registro excluído sai de vez. Informe o prazo em `retainDays`, o
+fuso da rotina e os textos da action que o Opus gera para expurgar:
+
+```ts
+export const ReportEntity = defineEntity({
+  name: 'report',
+  fields: { title: t.string() },
+  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.',
+  },
+})
+```
+
+O domínio que lista a entidade em `entities` ganha a action `report.purge-deleted` e a rotina
+diária `report.purge-deleted.daily`, às 3h30 no fuso declarado. Só o sistema executa a action,
+que fica fora do REST e da IA, e ela nunca expurga antes do prazo. Com `kyselyData` no runtime, o
+handler padrão apaga as linhas em lotes, das mais antigas para as mais novas; a rotina exige um
+[agendador](/docs/scheduler). Cada lote que apaga algo registra `opus.purge` no log com os ids
+removidos, e a execução termina com `opus.purge.total`, que traz a quantidade.
+
+Antes de declarar `retainDays`, confira as chaves estrangeiras que apontam para a tabela. Uma chave
+restritiva faz cada execução falhar no lote da linha travada, que está entre as mais antigas, e o
+expurgo fica parado até a chave ganhar cascata ou um `bindPurge` apagar os dependentes primeiro.
+
+Quando apagar a linha não basta, como ao remover arquivos em outro serviço, registre um handler
+próprio com `bindPurge`, de `@softize/opus/data`, em `purges` no mesmo domínio. O handler recebe o
+corte e só apaga o que foi excluído antes dele: é isso que garante o prazo. Para guardar o
+registro excluído para sempre, declare o motivo: `softDelete: { retain: 'forever', reason }`.
+
+O [`opus check`](/docs/cli) reprova `softDelete: true`, que não diz por quanto tempo o registro
+fica guardado. Opções, nomes gerados e erros estão no `docs/protocol.md` do pacote, §15, "Retenção
+e expurgo".
+
 ## Código em camelCase, banco em snake_case
 
 O schema tipado do Kysely e todas as consultas usam camelCase (`workspaceId`, `ghRepo`). O banco

package/src/ui/docs/content/scheduler.md

@@ -79,6 +79,10 @@ seção). Com schedules registrados e sem `scheduler`, o `start()` falha com
 `runtime.scheduler_required`. Um schedule com `enabled: false` não é registrado nem
 conferido, então pode apontar para uma action que ainda não existe no ambiente.
 
+Uma entidade com exclusão lógica e `retainDays` traz a própria rotina de expurgo, que o domínio
+registra junto com a action, como `report.purge-deleted.daily`. Ela também exige o `scheduler`.
+Veja "Exclusão lógica e expurgo" na página [Camada de dados](/docs/data).
+
 ## Preparar a action agendada
 
 O schedule executa a action como o sistema, sem uma pessoa por trás. Uma action que exige usuário