@softize/opus 18.3.0 → 18.5.0

package/CHANGELOG.md

@@ -7,6 +7,26 @@ 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.
 
+## 18.5.0 — 2026-09-22
+
+`Content` passa a concentrar estrutura e apresentação de blocos com cabeçalho e corpo: aceita
+`as="section" | "fieldset"`, `variant="page" | "section"` e moldura opcional com
+`frameVariant="default" | "legend"`. O novo
+`IconTile` mantém a moldura do ícone como composição explícita, permitindo usar o mesmo ícone com
+ou sem esse apoio visual.
+
+`ActionList` deixa de aplicar moldura por padrão. No layout `fill`, mantém o cabeçalho fixo sobre a
+cor da superfície, com borda inferior durante a rolagem. Filtros avançados podem escolher o tratamento das seções sem
+recriar o fieldset no consumidor. Labels de campos e detalhes compartilham a mesma escala tipográfica.
+
+## 18.4.0 — 2026-09-21
+
+`executions` acrescenta infraestrutura experimental de acompanhamento: snapshots versionados,
+store PostgreSQL com aviso transacional, assinante LISTEN com reconexão e SSE autenticado de
+invalidação. Não há instrumentação automática do runtime, nova fila nem controles de negócio.
+O consumidor precisa adaptar seus executores, persistir a revisão, autorizar leituras/avisos e
+reconciliar a projeção. Nenhuma migration ou conexão é criada ao importar o módulo.
+
 ## 18.3.0 — 2026-09-17
 
 `ActionList` passa a oferecer composição previsível para barras densas: filtros inline de valor

package/README.md

@@ -33,6 +33,7 @@ Um pacote (`@softize/opus`), uma versão. Cada categoria abaixo é um **subpath
 | `@softize/opus/audit` | `/console`, `/pg` | Destinos de auditoria |
 | `@softize/opus/log` | `/pino` | Adapter de log (console é o default no core) |
 | `@softize/opus/queue` | `/bullmq` | Execução de jobs em segundo plano |
+| `@softize/opus/executions` | `/memory`, `/pg`, `/pg-changes`, `/stream` | Projeção e SSE de acompanhamento (experimental, opt-in) |
 | `@softize/opus/events` | `/mitt` | EventBus em processo |
 | `@softize/opus/scheduler` | `/node-cron` | Adapter de agendamento (ação iniciada por tempo) |
 | `@softize/opus/storage` | `/fs`, `/s3` | Armazenamento de arquivos (experimental) |

package/docs/adr/0020-icon-tiles-are-explicitly-composed.md

@@ -0,0 +1,46 @@
+# ADR 0020 — Molduras de ícone são compostas explicitamente
+
+- **Status:** aceita.
+- **Data:** 2026-09-18.
+
+## Contexto
+
+Várias interfaces apresentam um ícone dentro de uma pequena superfície quadrada. A mesma forma
+aparecia incorporada em componentes como `FieldLegend`, `ItemMedia` e `EmptyMedia`, ou era
+reconstruída pelo consumidor. Em `FieldLegend`, isso também vinculava a moldura à variante da
+legenda: o consumidor conseguia escolher o ícone, mas não se ele deveria receber a superfície.
+
+## Decisão
+
+`IconTile` passa a representar a moldura visual não interativa de um ícone. Ele compartilha a
+escala de tamanhos dos controles, declara a cor por `context` e oferece os tratamentos `subtle` e
+`outline`.
+
+Slots que aceitam conteúdo, como `FieldLegend.icon`, continuam genéricos. O consumidor passa um
+ícone diretamente quando quer somente o glifo ou compõe `<IconTile><Icon /></IconTile>` quando a
+moldura reforça a hierarquia. `ItemMedia variant="icon"` e `EmptyMedia variant="icon"` reutilizam
+a mesma base visual porque essas variantes já prometem a moldura.
+
+`IconTile` é somente apresentação. Quando o ícone aciona algo, deve-se usar `Button` com tamanho
+de ícone e nome acessível.
+
+## Consequências
+
+- A presença da moldura deixa de ser uma regra implícita da legenda.
+- Tamanho, arredondamento e preenchimento convergem entre consumidores.
+- Um slot permanece flexível sem acumular propriedades como `iconFramed` ou `iconTile`.
+- Migrações devem distinguir molduras decorativas de botões e indicadores semânticos.
+
+## Alternativas descartadas
+
+- **Adicionar uma propriedade à `FieldLegend`:** resolveria apenas uma superfície e ampliaria o
+  contrato toda vez que outra composição precisasse escolher a moldura.
+- **Manter classes livres em cada consumidor:** preservaria divergências de escala e acabamento.
+- **Usar `Button` desabilitado:** comunicaria interatividade onde não existe ação.
+
+## Verificação
+
+- teste estrutural cobre tamanho, variante e tamanho do glifo de `IconTile`;
+- teste de `FieldLegend` confirma que o slot não adiciona moldura por conta própria;
+- teste da API pública garante que o componente e seus metadados sejam exportados;
+- documentação de `Field` mostra a composição explícita.

package/docs/adr/0021-content-carries-structure-and-semantic-element.md

@@ -0,0 +1,65 @@
+# ADR 0021 — Content reúne estrutura visual e elemento semântico
+
+- **Status:** aceita.
+- **Data:** 2026-09-19.
+
+## Contexto
+
+Regiões com título e corpo usam `Content`, mas grupos de formulário precisam reconstruir a mesma
+estrutura com `FieldSet` e `FieldLegend`. Molduras aplicadas diretamente em `DetailGroup` também
+separam visualmente o título dos dados que ele nomeia. Essa sobreposição aumenta a quantidade de
+estruturas que a documentação e os consumidores precisam combinar.
+
+## Decisão
+
+`Content` continua responsável pela anatomia `Header + Body` e passa a aceitar:
+
+- `framed`, que aplica a moldura à região inteira;
+- `as="fieldset"`, que renderiza a raiz como `fieldset` e o título como `legend`.
+- `frameVariant="legend"`, que integra visualmente a legenda à borda quando esse acabamento for
+  escolhido de forma explícita.
+
+O default permanece `as="section"` sem moldura. `FieldGroup` organiza campos dentro do corpo e
+`DetailGroup` preserva a semântica de lista de definições sem assumir a moldura da região.
+`FieldSet` permanece disponível para compatibilidade e para composições que não precisam da
+anatomia completa de `Content`.
+
+No modo `fieldset`, a legenda aceita somente o título. Contador, descrição e ações não são filhos
+válidos de `legend`; consumidores que precisarem dessas regiões devem mantê-las no corpo ou usar
+uma `section`. A escolha de `fieldset` não define o acabamento visual: quando `framed` estiver
+presente, a moldura é contínua por padrão. Os filtros avançados preservam a legenda integrada à
+borda declarando `frameVariant="legend"`.
+
+## Consequências
+
+- A mesma API nomeia e delimita regiões de leitura e grupos de formulário.
+- A escolha do elemento semântico não fica acoplada à presença da moldura.
+- O recorte visual da borda deixa de ser consequência implícita do elemento semântico.
+- A forma curta continua sendo o caminho comum, enquanto a composição explícita permanece
+  disponível nos dois elementos.
+- A migração de `FieldSet` pode ser gradual e não exige remoção nesta versão.
+
+## Alternativas consideradas
+
+### Criar Panel
+
+Separaria a moldura de `Content`, mas criaria outra raiz com header e body para documentar e
+compor. Foi descartada porque `Content` já possui essa responsabilidade.
+
+### Renomear FieldSet para FieldGroup
+
+Produziria simetria nominal com `DetailGroup`, mas perderia a distinção entre a fronteira semântica
+do formulário e o layout interno dos campos. Foi descartada porque `FieldGroup` já representa esse
+layout.
+
+### Adicionar um booleano fieldset
+
+Permitiria alternar o elemento, mas trataria semântica como estado visual. Foi descartada em favor
+de `as`, que explicita o elemento renderizado.
+
+## Verificação
+
+- Testes de UI confirmam `section` e heading como defaults.
+- Testes de UI confirmam `fieldset`, `legend`, props nativas e ausência de heading nesse modo.
+- Testes reprovam slots incompatíveis com a legenda.
+- A documentação demonstra `Content + DetailGroup` e `Content as="fieldset" + FieldGroup`.

package/docs/adr/0022-execution-monitoring-is-a-projection.md

@@ -0,0 +1,39 @@
+# ADR 0022 — Acompanhamento de execução é uma projeção, não um motor
+
+- **Status:** aceita para candidato local.
+- **Data:** 2026-09-21.
+
+## Contexto
+
+O runtime já oferece fila, scheduler e progresso. Consumidores também executam trabalho fora
+dele. Uma interface comum de acompanhamento não deve obrigar a migração desses motores nem
+centralizar regras de negócio, retry ou autorização no SDK.
+
+## Decisão
+
+Adicionar uma fronteira `executions`: snapshots operacionais versionados, store de projeção e
+avisos de invalidação. O executor fornece ID e revisão estáveis; o store só aceita revisão
+maior e preserva tenant e operação. A integração é explícita: não inferir cobertura de cron,
+filas ou processos arbitrários só por instalar o pacote.
+
+O snapshot não transporta input/output do job, erro livre, contatos ou credenciais. Ausência de
+heartbeat é distinta de heartbeat vencido. Nenhum desses estados dispara execução ou retry.
+Drivers concretos ficam fora do core. PostgreSQL persiste a projeção e publica NOTIFY na mesma
+transação; LISTEN e SSE são avisos transitórios, recuperados por leitura após reconexão.
+
+O transporte exige autorização do consumidor, limita o buffer e não envia snapshot pelo SSE.
+Não há nova fila, API de controle universal, tabela de notificações nem substituição de audit
+ou tracing. O consumidor trata falha de projeção fora da política de retry do negócio.
+
+## Alternativas
+
+Estender `JobHandle` para substituir todos os diários confundiria observação com autoridade.
+Um event bus em memória não atende workers em processos distintos. Replicar polling e stores
+por aplicação repetiria infraestrutura. A projeção opt-in preserva os motores existentes e
+permite adoção incremental, ao custo de instrumentação e reconciliação explícitas.
+
+## Verificação
+
+Testar revisão obsoleta, isolamento, snapshot malformado, aviso após commit, reconexão,
+revogação de acesso, limites de buffer e cancelamento. A API não deve aceitar payload arbitrário
+nem possuir método para executar/repetir trabalho. Publicar somente após os gates do SDK.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softize/opus",
-  "version": "18.3.0",
+  "version": "18.5.0",
   "description": "End-to-end action protocol for TypeScript. Single package with subpath exports (core + adapters).",
   "license": "MIT",
   "type": "module",
@@ -103,6 +103,26 @@
       "types": "./src/observability/drivers/opentelemetry.ts",
       "default": "./src/observability/drivers/opentelemetry.ts"
     },
+    "./executions": {
+      "types": "./src/executions/index.ts",
+      "default": "./src/executions/index.ts"
+    },
+    "./executions/memory": {
+      "types": "./src/executions/drivers/memory.ts",
+      "default": "./src/executions/drivers/memory.ts"
+    },
+    "./executions/pg": {
+      "types": "./src/executions/drivers/pg.ts",
+      "default": "./src/executions/drivers/pg.ts"
+    },
+    "./executions/pg-changes": {
+      "types": "./src/executions/drivers/pg-changes.ts",
+      "default": "./src/executions/drivers/pg-changes.ts"
+    },
+    "./executions/stream": {
+      "types": "./src/executions/stream.ts",
+      "default": "./src/executions/stream.ts"
+    },
     "./queue": {
       "types": "./src/queue/index.ts",
       "default": "./src/queue/index.ts"

package/src/executions/drivers/memory.ts

@@ -0,0 +1,39 @@
+import { executionNotice, executionQuery, executionSnapshot } from '../index.ts'
+import type { ExecutionChanges, ExecutionNotice, ExecutionSnapshot, ExecutionStore } from '../index.ts'
+
+/** Driver de testes. Não é durável nem observa outros processos. */
+export function memoryExecutions(): ExecutionStore & ExecutionChanges {
+  const snapshots = new Map<string, ExecutionSnapshot>()
+  const listeners = new Set<(notice: ExecutionNotice | null) => void>()
+  return {
+    async observe(input) {
+      const next = executionSnapshot(input)
+      const current = snapshots.get(next.id)
+      if (current && (current.revision >= next.revision || current.tenantId !== next.tenantId ||
+        current.operation !== next.operation || current.createdAt !== next.createdAt || current.trigger !== next.trigger)) return false
+      snapshots.set(next.id, next)
+      for (const listener of listeners) {
+        // Um assinante não participa da confirmação da projeção.
+        try { listener(executionNotice(next)) } catch { /* transporte já desconectado */ }
+      }
+      return true
+    },
+    async get(id, tenantId) {
+      executionQuery({ tenantId, operations: [] })
+      const snapshot = snapshots.get(id)
+      return snapshot && snapshot.tenantId === tenantId ? structuredClone(snapshot) : null
+    },
+    async list(input) {
+      const query = executionQuery(input)
+      return [...snapshots.values()]
+        .filter((snapshot) => snapshot.tenantId === query.tenantId && query.operations.includes(snapshot.operation))
+        .sort((a, b) => b.updatedAt.localeCompare(a.updatedAt) || a.id.localeCompare(b.id))
+        .slice(0, query.limit).map((snapshot) => structuredClone(snapshot))
+    },
+    subscribe(listener) {
+      const subscription = (notice: ExecutionNotice | null) => listener(notice)
+      listeners.add(subscription)
+      return () => { listeners.delete(subscription) }
+    },
+  }
+}

package/src/executions/drivers/pg-changes.ts

@@ -0,0 +1,104 @@
+import { parseExecutionNotice } from '../index.ts'
+import type { ExecutionChanges, ExecutionNotice } from '../index.ts'
+
+export interface ExecutionPgListener {
+  query(sql: string): Promise<unknown>
+  on(event: 'notification', listener: (message: { channel: string; payload?: string }) => void): unknown
+  on(event: 'error' | 'end', listener: () => void): unknown
+  removeListener(event: 'notification', listener: (message: { channel: string; payload?: string }) => void): unknown
+  removeListener(event: 'error' | 'end', listener: () => void): unknown
+  end(): Promise<unknown>
+}
+
+/** Uma conexão LISTEN compartilhada entre assinantes; nunca usar conexão de transação/pooler. */
+export function pgExecutionChanges(options: {
+  /** Conexão nova, já conectada e com connectionTimeoutMillis definido pelo consumidor. */
+  connect: () => Promise<ExecutionPgListener>
+  onError: (error: unknown) => void
+  channel?: string
+  reconnectMs?: number
+}): ExecutionChanges {
+  const channel = options.channel ?? 'opus_executions'
+  if (!/^[a-z_][a-z0-9_]{0,62}$/.test(channel)) throw new Error('Invalid execution channel')
+  const reconnectMs = options.reconnectMs ?? 1_000
+  if (!Number.isFinite(reconnectMs) || reconnectMs < 100) throw new Error('Invalid execution reconnect delay')
+  const listeners = new Set<{ notify: (notice: ExecutionNotice | null) => void; unavailable?: () => void }>()
+  let generation = 0
+  let cleanup: (() => void) | undefined
+  let retry: ReturnType<typeof setTimeout> | undefined
+
+  const report = (error: unknown) => { try { options.onError(error) } catch { /* diagnóstico não controla LISTEN */ } }
+  const broadcast = (notice: ExecutionNotice | null) => {
+    for (const listener of listeners) {
+      try { listener.notify(notice) } catch (error) { report(error) }
+    }
+  }
+  const close = (client: ExecutionPgListener) => {
+    const closingError = () => report(new Error('Execution change feed failed while closing'))
+    client.on('error', closingError)
+    void client.end().catch(report).finally(() => client.removeListener('error', closingError))
+  }
+
+  async function connect(): Promise<void> {
+    const ownGeneration = ++generation
+    try {
+      const client = await options.connect()
+      if (ownGeneration !== generation || listeners.size === 0) { close(client); return }
+      const notification = (message: { channel: string; payload?: string }) => {
+        if (message.channel !== channel) return
+        try { broadcast(parseExecutionNotice(JSON.parse(message.payload ?? ''))) } catch (error) { report(error) }
+      }
+      const disconnected = () => {
+        if (ownGeneration !== generation) return
+        report(new Error('Execution change feed disconnected'))
+        reconnect()
+      }
+      client.on('notification', notification)
+      client.on('error', disconnected)
+      client.on('end', disconnected)
+      cleanup = () => {
+        client.removeListener('notification', notification)
+        client.removeListener('error', disconnected)
+        client.removeListener('end', disconnected)
+        close(client)
+      }
+      await client.query(`LISTEN "${channel}"`)
+      if (ownGeneration === generation) broadcast(null)
+    } catch (error) {
+      if (ownGeneration !== generation) return
+      report(error)
+      reconnect()
+    }
+  }
+
+  function disconnect(): void {
+    ++generation
+    if (retry !== undefined) { clearTimeout(retry); retry = undefined }
+    const dispose = cleanup
+    cleanup = undefined
+    dispose?.()
+  }
+
+  function reconnect(): void {
+    disconnect()
+    const disconnectedGeneration = generation
+    for (const listener of [...listeners]) {
+      try { listener.unavailable?.() } catch (error) { report(error) }
+    }
+    if (generation === disconnectedGeneration && listeners.size > 0) {
+      retry = setTimeout(() => { retry = undefined; void connect() }, reconnectMs)
+    }
+  }
+
+  return {
+    subscribe(listener, onUnavailable) {
+      const subscription = { notify: listener, unavailable: onUnavailable }
+      listeners.add(subscription)
+      if (listeners.size === 1) void connect()
+      return () => {
+        listeners.delete(subscription)
+        if (listeners.size === 0) disconnect()
+      }
+    },
+  }
+}

package/src/executions/drivers/pg.ts

@@ -0,0 +1,74 @@
+import { executionQuery, executionSnapshot } from '../index.ts'
+import type { ExecutionSnapshot, ExecutionStore } from '../index.ts'
+
+export interface ExecutionPgPool {
+  query(text: string, values?: unknown[]): Promise<{ rows: Record<string, unknown>[] }>
+}
+
+export interface PgExecutionsOptions {
+  pool: ExecutionPgPool
+  table?: string
+  channel?: string
+}
+
+function sqlIdentifier(value: string): string {
+  if (!/^[a-z_][a-z0-9_]{0,62}$/.test(value)) throw new Error('Invalid execution SQL identifier')
+  return `"${value}"`
+}
+
+/** SQL para a migration do consumidor. O driver não aplica DDL nem grants automaticamente. */
+export function executionTableSql(table = 'execution_snapshots'): string {
+  const name = sqlIdentifier(table)
+  return `CREATE TABLE ${name} (
+    id text PRIMARY KEY,
+    tenant_id text,
+    operation text NOT NULL,
+    revision bigint NOT NULL CHECK (revision > 0),
+    updated_at timestamptz NOT NULL,
+    snapshot jsonb NOT NULL
+  );
+  CREATE INDEX ON ${name} (tenant_id, operation, updated_at DESC, id);`
+}
+
+/** Escrita do snapshot e NOTIFY pertencem à mesma transação PostgreSQL. */
+export function pgExecutions(options: PgExecutionsOptions): ExecutionStore {
+  const table = sqlIdentifier(options.table ?? 'execution_snapshots')
+  const channel = options.channel ?? 'opus_executions'
+  sqlIdentifier(channel)
+  return {
+    async observe(input) {
+      const next = executionSnapshot(input)
+      const result = await options.pool.query(`
+        WITH changed AS (
+          INSERT INTO ${table} AS current (id, tenant_id, operation, revision, updated_at, snapshot)
+          VALUES ($1, $2, $3, $4, $5, $6::jsonb)
+          ON CONFLICT (id) DO UPDATE SET revision = EXCLUDED.revision,
+            updated_at = EXCLUDED.updated_at, snapshot = EXCLUDED.snapshot
+          WHERE current.revision < EXCLUDED.revision
+            AND current.tenant_id IS NOT DISTINCT FROM EXCLUDED.tenant_id
+            AND current.operation = EXCLUDED.operation
+            AND current.snapshot->>'createdAt' = EXCLUDED.snapshot->>'createdAt'
+            AND current.snapshot->>'trigger' = EXCLUDED.snapshot->>'trigger'
+          RETURNING id, tenant_id, operation, revision
+        )
+        SELECT pg_notify($7, json_build_object('id', id, 'tenantId', tenant_id,
+          'operation', operation, 'revision', revision)::text) FROM changed`,
+      [next.id, next.tenantId, next.operation, next.revision, next.updatedAt, JSON.stringify(next), channel])
+      return result.rows.length > 0
+    },
+    async get(id, tenantId) {
+      executionQuery({ tenantId, operations: [] })
+      const result = await options.pool.query(`SELECT snapshot FROM ${table} WHERE id = $1 AND tenant_id IS NOT DISTINCT FROM $2`, [id, tenantId])
+      const row = result.rows[0]
+      return row ? executionSnapshot(row.snapshot as ExecutionSnapshot) : null
+    },
+    async list(input) {
+      const query = executionQuery(input)
+      if (query.operations.length === 0) return []
+      const result = await options.pool.query(`SELECT snapshot FROM ${table}
+        WHERE tenant_id IS NOT DISTINCT FROM $1 AND operation = ANY($2::text[])
+        ORDER BY updated_at DESC, id ASC LIMIT $3`, [query.tenantId, query.operations, query.limit])
+      return result.rows.map((row) => executionSnapshot(row.snapshot as ExecutionSnapshot))
+    },
+  }
+}

package/src/executions/index.ts

@@ -0,0 +1,129 @@
+/** Projeção operacional. Estados e revisões são informados pelo executor, nunca inferidos aqui. */
+export type ExecutionStatus = 'queued' | 'running' | 'paused' | 'succeeded' | 'failed' | 'cancelled'
+export type ExecutionTrigger = 'manual' | 'schedule' | 'queue' | 'system'
+
+export interface ExecutionSnapshot {
+  id: string
+  tenantId: string | null
+  operation: string
+  revision: number
+  status: ExecutionStatus
+  trigger: ExecutionTrigger
+  /** Tentativa da mesma execução; o executor continua responsável por sua política de retry. */
+  attempt: number
+  createdAt: string
+  updatedAt: string
+  startedAt?: string
+  finishedAt?: string
+  heartbeatAt?: string
+  progress?: { completed: number; total?: number }
+}
+
+export interface ExecutionNotice {
+  id: string
+  tenantId: string | null
+  operation: string
+  revision: number
+}
+
+export interface ExecutionQuery {
+  /** Obrigatório: null seleciona somente execuções sem tenant, nunca todos os tenants. */
+  tenantId: string | null
+  operations: readonly string[]
+  limit?: number
+}
+
+export interface ExecutionStore {
+  /** false: revisão obsoleta/repetida ou tentativa de alterar a identidade do registro. */
+  observe(snapshot: ExecutionSnapshot): Promise<boolean>
+  get(id: string, tenantId: string | null): Promise<ExecutionSnapshot | null>
+  list(query: ExecutionQuery): Promise<ExecutionSnapshot[]>
+}
+
+export interface ExecutionChanges {
+  /** null exige nova fotografia após conectar/reconectar. Não há replay de NOTIFY. */
+  subscribe(listener: (notice: ExecutionNotice | null) => void, onUnavailable?: () => void): () => void
+}
+
+const statuses: readonly ExecutionStatus[] = ['queued', 'running', 'paused', 'succeeded', 'failed', 'cancelled']
+const triggers: readonly ExecutionTrigger[] = ['manual', 'schedule', 'queue', 'system']
+
+function identifier(value: unknown): asserts value is string {
+  if (typeof value !== 'string' || value.length < 1 || value.length > 200 || /[\x00-\x1f]/.test(value)) {
+    throw new Error('Invalid execution identifier')
+  }
+}
+
+function integer(value: unknown, min: number): asserts value is number {
+  if (!Number.isSafeInteger(value) || (value as number) < min) throw new Error('Invalid execution counter')
+}
+
+function date(value: unknown): asserts value is string {
+  if (typeof value !== 'string' || !/^\d{4}-\d{2}-\d{2}T.*Z$/.test(value) || !Number.isFinite(Date.parse(value))) {
+    throw new Error('Invalid execution timestamp')
+  }
+}
+
+/** Valida e seleciona explicitamente campos; propriedades extras não chegam à persistência. */
+export function executionSnapshot(input: ExecutionSnapshot): ExecutionSnapshot {
+  identifier(input.id)
+  identifier(input.operation)
+  if (input.tenantId !== null) identifier(input.tenantId)
+  integer(input.revision, 1)
+  integer(input.attempt, 0)
+  if (!statuses.includes(input.status) || !triggers.includes(input.trigger)) throw new Error('Invalid execution state')
+  date(input.createdAt)
+  date(input.updatedAt)
+  const result: ExecutionSnapshot = {
+    id: input.id, tenantId: input.tenantId, operation: input.operation,
+    revision: input.revision, status: input.status, trigger: input.trigger, attempt: input.attempt,
+    createdAt: new Date(input.createdAt).toISOString(), updatedAt: new Date(input.updatedAt).toISOString(),
+  }
+  for (const key of ['startedAt', 'finishedAt', 'heartbeatAt'] as const) {
+    if (input[key] !== undefined) { date(input[key]); result[key] = new Date(input[key]).toISOString() }
+  }
+  if (Date.parse(result.updatedAt) < Date.parse(result.createdAt)) throw new Error('Invalid execution chronology')
+  if (input.progress !== undefined) {
+    integer(input.progress.completed, 0)
+    result.progress = { completed: input.progress.completed }
+    if (input.progress.total !== undefined) {
+      integer(input.progress.total, input.progress.completed)
+      result.progress.total = input.progress.total
+    }
+  }
+  return result
+}
+
+export function executionNotice(snapshot: ExecutionSnapshot): ExecutionNotice {
+  return { id: snapshot.id, tenantId: snapshot.tenantId, operation: snapshot.operation, revision: snapshot.revision }
+}
+
+export function parseExecutionNotice(value: unknown): ExecutionNotice {
+  if (typeof value !== 'object' || value === null) throw new Error('Invalid execution notice')
+  const input = value as ExecutionNotice
+  identifier(input.id)
+  identifier(input.operation)
+  if (input.tenantId !== null) identifier(input.tenantId)
+  integer(input.revision, 1)
+  return { id: input.id, tenantId: input.tenantId, operation: input.operation, revision: input.revision }
+}
+
+export function executionQuery(query: ExecutionQuery): Required<ExecutionQuery> {
+  if (query.tenantId !== null) identifier(query.tenantId)
+  if (!Array.isArray(query.operations) || query.operations.length > 100) throw new Error('Invalid execution operations')
+  for (const operation of query.operations) identifier(operation)
+  const limit = query.limit ?? 50
+  integer(limit, 1)
+  if (limit > 200) throw new Error('Execution query limit exceeds 200')
+  return { tenantId: query.tenantId, operations: [...new Set(query.operations)], limit }
+}
+
+/** Diagnóstico de observação; nunca transforma o estado autoritativo em failed nem autoriza retry. */
+export function executionLiveness(snapshot: ExecutionSnapshot, now: number, staleAfterMs: number): 'inactive' | 'unknown' | 'fresh' | 'stale' {
+  if (!Number.isFinite(now) || !Number.isFinite(staleAfterMs) || staleAfterMs <= 0) throw new Error('Invalid liveness clock')
+  if (snapshot.status !== 'running') return 'inactive'
+  if (snapshot.heartbeatAt === undefined) return 'unknown'
+  const heartbeat = Date.parse(snapshot.heartbeatAt)
+  if (!Number.isFinite(heartbeat) || heartbeat > now) return 'unknown'
+  return now - heartbeat >= staleAfterMs ? 'stale' : 'fresh'
+}