@softize/opus 18.3.0 → 18.4.0

package/CHANGELOG.md

@@ -7,6 +7,14 @@ 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

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.3.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/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/docs/content/executions.md

@@ -0,0 +1,157 @@
+---
+title: Acompanhamento de execuções
+---
+
+# Acompanhamento de execuções
+
+Use `executions` para reunir progresso e resultado de tarefas executadas por motores diferentes.
+O módulo é experimental e opt-in: instalar o Opus não passa a descobrir crons, filas ou workers.
+O executor continua dono do estado; este recurso mantém uma fotografia para consulta.
+
+Para colocar trabalho em segundo plano, use [Filas](/docs/queue). Para acompanhar trabalho já
+existente, adapte seu executor à projeção abaixo. Não usar a projeção para decidir reenvio ou retry.
+
+## Publicar uma fotografia
+
+O executor precisa conservar um ID e uma revisão crescente, inclusive entre tentativas e
+reinícios. Grave essa revisão com o estado autoritativo; não use `Date.now()` nem um contador
+exclusivo da memória do processo. O exemplo usa o driver em memória somente para demonstrar o
+protocolo:
+
+```ts
+import { memoryExecutions } from '@softize/opus/executions/memory'
+
+const executions = memoryExecutions()
+await executions.observe({
+  id: 'export-42',
+  tenantId: 'organization-7',
+  operation: 'catalog.export',
+  revision: 3,
+  attempt: 1,
+  status: 'running',
+  trigger: 'schedule',
+  createdAt: '2026-09-21T10:00:00.000Z',
+  updatedAt: '2026-09-21T10:01:00.000Z',
+  heartbeatAt: '2026-09-21T10:01:00.000Z',
+  progress: { completed: 150, total: 500 },
+})
+```
+
+`observe` retorna `false` para uma revisão repetida ou obsoleta e para uma tentativa de trocar
+tenant, operação, criação ou disparo do mesmo ID. O ID é único em todo o store, não por tenant.
+Cron que enfileira trabalho continua com
+`trigger: 'schedule'`; entrar na fila não cria outra execução. Retomada mantém o ID e avança
+revisão/tentativa conforme o executor. A projeção não valida transições de negócio.
+
+Uma falha de projeção lança erro para o adaptador tratar. Registrar essa falha e reconciliar
+depois a partir do executor; não deixar o erro provocar retry de um efeito já realizado.
+`observe` não contém proteção automática para o fluxo de negócio do consumidor.
+
+## Persistência e processos separados
+
+Use `pgExecutions({ pool, table?, channel? })` para persistir. O pool é fornecido pelo consumidor,
+sem dependência de conexão global. `executionTableSql(table?)` devolve o DDL para incluir na
+migration; não executa a migration, grants ou retenção. Nomes de tabela/canal aceitam um
+identificador SQL simples. Tabela padrão: `execution_snapshots`; canal: `opus_executions`.
+
+O driver atualiza somente uma revisão maior e publica NOTIFY no mesmo statement. Em uma
+transação externa, o aviso só sai no commit. Rollback não publica progresso. O snapshot é
+durável; o aviso não é histórico nem fila de entrega.
+
+`pgExecutionChanges({ connect, onError, channel?, reconnectMs? })` compartilha uma conexão
+LISTEN entre seus assinantes. `connect` deve entregar uma conexão nova, já conectada, dedicada
+e com timeout de conexão configurado. Não fornecer uma conexão emprestada por um pooler
+transacional. O driver fecha a conexão quando sai o último assinante, registra falhas por
+`onError` e tenta reconectar após `reconnectMs` (padrão: 1.000 ms; mínimo: 100 ms).
+
+Após cada conexão, o assinante recebe `null`: refaça a fotografia. Uma conexão nova não recupera
+avisos perdidos. O consumidor precisa reconciliar também snapshots que não foram gravados por
+falha de banco; reconectar SSE não corrige uma projeção que nunca foi atualizada.
+
+## Atualizar a interface por SSE
+
+`executionStream` devolve uma `Response` Web para montar em uma rota do servidor. O consumidor
+fornece autenticação e autorização; nenhum token é recebido pela URL ou pelo protocolo do SDK.
+
+```ts
+import { executionStream } from '@softize/opus/executions/stream'
+import type { ExecutionChanges, ExecutionNotice } from '@softize/opus/executions'
+
+async function openProgress(
+  request: Request,
+  changes: ExecutionChanges,
+  authorize: (notice: ExecutionNotice | null) => Promise<boolean>,
+  logError: (error: unknown) => void,
+) {
+  return executionStream({ changes, authorize, signal: request.signal, onError: logError })
+}
+```
+
+Para `authorize(null)`, verificar sessão e direito de acompanhar. Para um aviso, verificar
+também tenant, operação e recurso exato. Essa verificação ocorre novamente durante o stream,
+inclusive nos heartbeats e antes de emitir uma invalidação. Heartbeats revalidam a sessão
+independentemente da fila de avisos: a função pode receber um aviso e `null` concorrentemente.
+As actions de leitura devem aplicar a mesma política: filtrar a
+consulta por tenant não substitui autorização.
+
+O cliente recebe somente `event: invalidate` com `{}`. Ao recebê-lo, invalidar as queries das
+actions autorizadas. Manter uma conexão compartilhada no provider da aplicação, não uma por
+card. A primeira invalidação e a reconexão exigem nova fotografia; não há `Last-Event-ID` nem
+replay. O navegador pode usar `EventSource` com cookies same-origin e sua reconexão nativa.
+
+Heartbeat padrão: 15 segundos. Duração máxima padrão: cinco minutos, seguida de reconexão.
+O stream encerra na revogação de acesso, abort, falha de autorização, perda de LISTEN ou cliente lento. Há limites
+de 128 avisos pendentes e 16 frames na saída; excedê-los encerra a conexão para nova fotografia,
+sem acumular um log em memória. Sessão é reavaliada no máximo a cada heartbeat enquanto a
+autorização responde; configure timeout no serviço de autorização para não mantê-la pendente.
+
+IDs, tenant e operação nos avisos são metadados operacionais internos. Não usar CPF, telefone,
+e-mail ou segredo nesses identificadores. PostgreSQL NOTIFY não é uma fronteira de autorização:
+restringir as credenciais e o acesso ao banco. Nada do aviso é copiado para o SSE.
+
+## Detectar ausência de sinal
+
+`executionLiveness(snapshot, nowMs, staleAfterMs)` retorna `inactive` quando não está em
+execução, `unknown` quando não há heartbeat confiável, `fresh` com sinal recente e `stale`
+quando o limite foi atingido. Heartbeat futuro é `unknown`, para não esconder diferença de
+relógio. O chamador define a tolerância de acordo com a frequência do worker.
+
+`stale` não altera `status`, não confirma falha e não autoriza retomar. Pausar, cancelar e
+repetir continuam comandos do domínio. Logs completos e notificações pessoais também
+continuam fora desta projeção.
+
+## Referência de ExecutionSnapshot
+
+| Campo | Contrato |
+| --- | --- |
+| `id`, `tenantId`, `operation` | ID operacional, tenant explícito ou `null` e código da operação; IDs textuais limitados a 200 caracteres |
+| `revision`, `attempt` | Inteiros seguros; revisão positiva e tentativa não negativa |
+| `status` | `queued`, `running`, `paused`, `succeeded`, `failed` ou `cancelled` |
+| `trigger` | `manual`, `schedule`, `queue` ou `system`; imutável para o mesmo ID |
+| `createdAt`, `updatedAt` | Datas UTC; atualização não pode anteceder criação |
+| `startedAt`, `finishedAt`, `heartbeatAt` | Datas UTC opcionais |
+| `progress` | `completed` não negativo e `total` opcional, não inferior ao concluído; ambos inteiros seguros |
+
+`executionSnapshot` valida, normaliza datas e seleciona somente os campos acima.
+`executionNotice` extrai ID, tenant, operação e revisão. `parseExecutionNotice` valida dados
+recebidos pelo transporte e remove propriedades extras.
+
+## Referência de ExecutionStore e ExecutionChanges
+
+| Método | Contrato |
+| --- | --- |
+| `observe(snapshot)` | Grava somente revisão nova; retorna se alterou a projeção |
+| `get(id, tenantId)` | Busca escopada; devolve snapshot ou `null` |
+| `list({ tenantId, operations, limit? })` | Lista por atualização decrescente e ID; operações obrigatórias, limite padrão 50 e máximo 200 |
+| `subscribe(listener, onUnavailable?)` | Assina aviso ou `null` de reconexão; comunica perda do transporte ao segundo callback e devolve função de saída |
+
+`tenantId: null` seleciona somente execuções sem tenant, não todos os tenants. Lista de operações
+vazia não retorna registros. `executionQuery` valida esse recorte. O catálogo de operações,
+autorização, paginação completa do histórico e retenção pertencem ao consumidor; esta leitura
+limitada atende os snapshots recentes, não substitui uma action `kind: 'list'`.
+
+## Limites desta etapa
+
+Não há adaptadores automáticos de runtime, BullMQ ou scheduler, heartbeat automático,
+reconciliação agendada, UI pronta ou mecanismo genérico de pausa. Esses consumidores precisam
+ser implementados e testados antes de afirmar que todos os processos estão acompanhados.

package/src/ui/docs/registry.tsx

@@ -33,6 +33,7 @@ import eventsMd from "./content/events.md?raw";
 import logMd from "./content/log.md?raw";
 import observabilityMd from "./content/observability.md?raw";
 import queueMd from "./content/queue.md?raw";
+import executionsMd from "./content/executions.md?raw";
 import schedulerMd from "./content/scheduler.md?raw";
 import actionsMd from "./content/actions.md?raw";
 import dataMd from "./content/data.md?raw";
@@ -321,6 +322,12 @@ export const PROTOCOL_SECTIONS: DocSection[] = [
             badge: "queue",
             render: doc(queueMd),
           },
+          {
+            slug: "executions",
+            title: "Acompanhamento de execuções",
+            badge: "executions",
+            render: doc(executionsMd),
+          },
           {
             slug: "scheduler",
             title: "Agendador",