@softize/opus 18.2.0 → 18.4.0

package/CHANGELOG.md

@@ -7,6 +7,32 @@ 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.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
+único abraçam o conteúdo até o limite da barra, a busca ocupa o espaço flexível restante, dropdowns
+podem ser mais largos que o controle e filtros pesquisáveis podem omitir a opção vazia. Valores de
+repouso, ícones por filtro, agrupamento de tipo de data com período e ícones nas seções avançadas
+ficam declarados pelas props do pattern. A barra deixa de transformar filtros inline em chips por
+falta de espaço; a página preserva sua largura mínima e delega o overflow à superfície correta.
+
+Listagens podem usar `layout="fill"` para ocupar a altura disponível e manter a rolagem dentro da
+tabela, com cabeçalho fixo e a mesma moldura nos estados vazio, carregando e erro. `Page` e
+`Presentation` propagam esse contrato sem criar uma segunda rolagem no frame.
+
+`MetricCard` aceita `secondaryMetric` para uma leitura complementar diretamente relacionada,
+exibida como lâmina posterior com explicação própria. `FieldLegend` aceita ícone e a variante
+`section`; o `Select` equaliza a ação de limpar com os demais campos e permite que sua lista cresça
+além do gatilho sem alterar o layout.
+
 ## 18.2.0 — 2026-09-16
 
 `Presentation` passa a aceitar um body serializável baseado em componente. O contrato continua

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/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.2.0",
+  "version": "18.4.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/registry/skills/build-opus-ui/SKILL.md

@@ -37,8 +37,9 @@ existentes, mantendo navegação observável e componentes reutilizáveis sem la
    permanece sempre presente.
 6. Deixar ausência, paginação e largura de filtro com o pattern: célula e `DetailField` já
    representam valor ausente (`EmptyValue`, `empty` para o significado do domínio); listas
-   paginam pela primitiva `Pagination`; selects inline de filtro têm largura fixa. Não reescrever
-   esses defaults na tela.
+   paginam pela primitiva `Pagination`; selects inline de valor único abraçam o valor até o limite
+   definido pela barra, e o menu pode ser mais largo que o controle. Não reescrever esses defaults
+   na tela.
 7. Tratar página, filtro, seleção e modal importante como estado navegável por URL quando
    o produto precisa de deep link, back/forward ou refresh. Em `Presentation`, declarar `route`
    no artefato e deixar o adaptador apenas conectar a spec ao router da aplicação.

package/registry/skills/build-opus-ui/references/ui-patterns.md

@@ -122,9 +122,10 @@ ContentDescription, ContentMeta, ContentActions) + ContentBody`. `ContentHeader`
 - Paginação é a primitiva `Pagination`, inclusive dentro de `ActionList`. Número de página tem
   largura mínima e cresce com os dígitos; só as setas são quadradas. Não montar paginador com
   `Button` nem prender números a `size-*`.
-- Select inline de filtro tem largura fixa (`w-40`; lookup e múltiplo `w-52`): a label trunca, o
-  valor trunca no trigger e a opção inteira fica na lista. Não dimensionar filtro pelo conteúdo
-  nem pela label; o modal usa `w-full`.
+- Select inline de valor único abraça o valor selecionado até `max-w-80`. Acima desse limite, o
+  valor trunca no gatilho e a opção inteira permanece na lista, que pode ser mais larga.
+  Multiseleção mantém `w-52`; o modal usa `w-full`. Não recalcular essa largura na tela nem
+  dimensioná-la pela label do filtro.
 - Catálogo e API efetivos vêm dos exports da versão instalada, não de memória ou exemplo antigo.
 - Em componentes semânticos, `context` responde por que há destaque e `variant` responde como ele
   aparece. O vocabulário canônico é `neutral | primary | info | success | warning | danger`; as

package/src/core/errors.ts

@@ -93,7 +93,6 @@ class ActionErrorImpl extends Error implements ActionError {
   readonly i18nParams?: Record<string, unknown>
   readonly field?: string
   readonly issues?: ValidationIssue[]
-  override readonly cause?: unknown
   readonly meta?: Record<string, unknown>
 
   constructor(input: ErrorInput) {

package/src/core/types.ts

@@ -598,6 +598,10 @@ export interface FilterSpec {
 
   type: 'text' | 'select' | 'lookup' | 'date' | 'number'
   multiple?: boolean
+  /** Habilita busca local nas opções de um `select`; `lookup` já é pesquisável por natureza. */
+  searchable?: boolean
+  /** Quando `false`, a interface omite a opção vazia. Limpar restaura o default do filtro. */
+  allowEmpty?: boolean
   mode?: 'server' | 'client'
   operators?: FilterOp[]
   path?: string

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'
+}

package/src/executions/stream.ts

@@ -0,0 +1,123 @@
+import type { ExecutionChanges, ExecutionNotice } from './index.ts'
+
+export interface ExecutionStreamOptions {
+  changes: ExecutionChanges
+  /** null: sessão e direito de acompanhar; notice: também autorizar a execução exata. */
+  authorize: (notice: ExecutionNotice | null) => Promise<boolean>
+  signal?: AbortSignal
+  heartbeatMs?: number
+  /** Renova a conexão e a autorização mesmo se não houver atividade. */
+  maxDurationMs?: number
+  onError: (error: unknown) => void
+}
+
+/**
+ * SSE sem dados de negócio. Ler a fotografia por actions autorizadas após cada invalidate.
+ * Assinar antes da primeira invalidação evita a lacuna entre fotografia e assinatura.
+ */
+export async function executionStream(options: ExecutionStreamOptions): Promise<Response> {
+  const heartbeatMs = options.heartbeatMs ?? 15_000
+  const maxDurationMs = options.maxDurationMs ?? 300_000
+  if (!Number.isFinite(heartbeatMs) || heartbeatMs < 100 || !Number.isFinite(maxDurationMs) || maxDurationMs < heartbeatMs) {
+    throw new Error('Invalid execution stream timing')
+  }
+  if (options.signal?.aborted) return new Response(null, { status: 204 })
+  if (!await options.authorize(null)) return new Response(null, { status: 403 })
+  if (options.signal?.aborted) return new Response(null, { status: 204 })
+
+  const encoder = new TextEncoder()
+  let close = () => {}
+  let cancelled = false
+  const stream = new ReadableStream<Uint8Array>({
+    start(controller) {
+      let closed = false
+      let busy = false
+      let pendingReset = false
+      let pinging = false
+      let sessionCheck: Promise<boolean> | undefined
+      const pending = new Map<string, ExecutionNotice>()
+      let unsubscribe: (() => void) | undefined
+      let heartbeat: ReturnType<typeof setInterval> | undefined
+      let deadline: ReturnType<typeof setTimeout> | undefined
+      close = () => {
+        if (closed) return
+        closed = true
+        pending.clear()
+        unsubscribe?.()
+        clearInterval(heartbeat)
+        clearTimeout(deadline)
+        options.signal?.removeEventListener('abort', close)
+        if (!cancelled) controller.close()
+      }
+      const send = (message: string) => {
+        if (closed) return
+        // Uma conexão lenta reconecta e refaz a fotografia; nunca acumula progresso sem limite.
+        if ((controller.desiredSize ?? 0) <= 0) { close(); return }
+        controller.enqueue(encoder.encode(message))
+      }
+      const invalidate = () => send('event: invalidate\ndata: {}\n\n')
+      const report = (error: unknown) => { try { options.onError(error) } catch { /* não vazar erro no SSE */ } }
+
+      function sessionAllowed(): Promise<boolean> {
+        sessionCheck ??= Promise.resolve().then(() => options.authorize(null)).finally(() => { sessionCheck = undefined })
+        return sessionCheck
+      }
+
+      // A fila de autorizações por recurso não pode segurar a renovação da sessão ou o heartbeat.
+      async function ping(): Promise<void> {
+        if (pinging || closed) return
+        pinging = true
+        try {
+          if (!await sessionAllowed()) close()
+          else send(': heartbeat\n\n')
+        } catch (error) { report(error); close() }
+        finally { pinging = false }
+      }
+
+      async function flush(): Promise<void> {
+        if (busy || closed) return
+        busy = true
+        try {
+          while (!closed && (pending.size > 0 || pendingReset)) {
+            const notices = [...pending.values()]
+            pending.clear()
+            let allowed = pendingReset
+            pendingReset = false
+            if (!await sessionAllowed()) { close(); break }
+            for (const notice of notices) {
+              if (closed) break
+              if (await options.authorize(notice)) allowed = true
+            }
+            if (allowed && !closed) {
+              if (!await sessionAllowed()) { close(); break }
+              invalidate()
+            }
+          }
+        } catch (error) { report(error); close() }
+        finally { busy = false }
+      }
+
+      const dispose = options.changes.subscribe((notice) => {
+        if (closed) return
+        if (notice === null) pendingReset = true
+        else pending.set(notice.id, notice)
+        if (pending.size > 128) { close(); return }
+        void flush()
+      }, close)
+      unsubscribe = dispose
+      if (closed) { dispose(); return }
+      options.signal?.addEventListener('abort', close, { once: true })
+      if (options.signal?.aborted) { close(); return }
+      heartbeat = setInterval(() => { void ping() }, heartbeatMs)
+      deadline = setTimeout(close, maxDurationMs)
+      pendingReset = true
+      void flush()
+    },
+    cancel() { cancelled = true; close() },
+  }, { highWaterMark: 16 })
+  return new Response(stream, { headers: {
+    'Content-Type': 'text/event-stream',
+    'Cache-Control': 'no-cache, no-store',
+    'X-Accel-Buffering': 'no',
+  } })
+}

package/src/ui/components/patterns/data-state.tsx

@@ -75,7 +75,7 @@ export function DataState({
   if (colSpan !== undefined) {
     return (
       <tr data-slot="data-state" data-status={status}>
-        <td colSpan={colSpan} className="px-4 py-4 text-center text-sm">
+        <td colSpan={colSpan} className="px-4 py-4 text-center align-middle text-sm">
           {surface}
         </td>
       </tr>