Execuções e auditoria

Cada execução tem um estado atual (task_runs ou platform_task_runs) e uma trilha append-only (task_run_events ou platform_task_run_events). As regras que o banco impõe sobre elas estão em Auditoria das execuções.

Ciclo de vida

A trilha registra cada passo: queued, sent, received, started, progress, retry_scheduled, succeeded, failed, skipped, dead_lettered, released_on_shutdown e redriven.

Status pela API

GET /task-runs/{runId} devolve o status de uma run do tenant de quem chama e exige a permissão access.task_runs.read. A leitura vai primeiro ao Valkey e, numa falta, ao PostgreSQL. Toda transição commitada remove a cópia em cache; uma run ainda em andamento fica em cache por 5 s, e uma run encerrada, por um dia.

Enquanto a autenticação é reconstruída, a rota responde 401 como as outras rotas protegidas.

Tabelas

`task_runs`

Estado atual de cada execução de tenant, com o mesmo run_id do outbox e do envelope; nunca é apagada.

Coluna	Tipo	Nulo	Observação
`run_id`	`uuid`	não
`tenant_id`	`bigint`	não
`name`	`text`	não
`queue`	`text`	não
`trigger`	`text`	não
`actor_kind`	`text`	não
`actor_label`	`text`	não
`correlation_id`	`uuid`	não
`causation_id`	`uuid`	não
`status`	`text`	não
`attempts`	`integer`	não	padrão `0`
`progress`	`smallint`	não	padrão `0`
`outcome`	`jsonb`	não	padrão `'{}'::jsonb`
`queued_at`	`timestamptz`	não	padrão `clock_timestamp()`
`started_at`	`timestamptz`	sim
`finished_at`	`timestamptz`	sim
`updated_at`	`timestamptz`	não	padrão `clock_timestamp()`

Chaves estrangeiras

tenant_id → tenants.id

Referenciada por: task_run_events, task_run_user_actors.

Garantido pelo banco

Tipo	Nome	Definição
CHECK	`task_runs_actor_kind_check`	`CHECK ((actor_kind IN ('user', 'system')))`
CHECK	`task_runs_actor_label_check`	`CHECK (((length(actor_label) >= 1) AND (length(actor_label) <= 128)))`
CHECK	`task_runs_attempts_check`	`CHECK ((attempts >= 0))`
CHECK	`task_runs_check`	`CHECK (((status IN ('succeeded', 'failed', 'skipped')) = (finished_at IS NOT NULL)))`
CHECK	`task_runs_name_check`	`CHECK ((name ~ '^[a-z][a-z0-9._-]{1,63}$'))`
CHECK	`task_runs_outcome_check`	`CHECK (((jsonb_typeof(outcome) = 'object') AND (octet_length((outcome)::text) <= 2048)))`
CHECK	`task_runs_progress_check`	`CHECK (((progress >= 0) AND (progress <= 100)))`
CHECK	`task_runs_queue_check`	`CHECK ((queue IN ('critical', 'default', 'bulk', 'maintenance')))`
CHECK	`task_runs_status_check`	`CHECK ((status IN ('queued', 'running', 'retrying', 'succeeded', 'failed', 'skipped')))`
CHECK	`task_runs_trigger_check`	`CHECK ((trigger IN ('dispatch', 'event', 'redrive')))`
PK	`task_runs_pkey`	`PRIMARY KEY (run_id)`
Constraint trigger	`task_runs_user_actor_present`	adiada até o commit (`DEFERRABLE INITIALLY DEFERRED`)
UNIQUE	`task_runs_run_id_tenant_id_key`	`UNIQUE (run_id, tenant_id)`
Trigger	`task_runs_identity_fixed`	só colunas de ciclo de vida podem mudar
Trigger	`task_runs_never_deleted`	recusa `DELETE` (e `UPDATE`, nas tabelas de origem e ator)
Trigger	`task_runs_no_truncate`	recusa `TRUNCATE`

Fora do banco

actor_kind = 'platform_operator' ainda não existe: runs de operador de plataforma são recusadas até haver tabela de origem própria.

`task_run_user_actors`

O usuário e a membership de uma run disparada por pessoa (actor_kind = 'user'). Obrigatória na mesma transação.

Coluna	Tipo	Nulo
`run_id`	`uuid`	não
`tenant_id`	`bigint`	não
`user_id`	`bigint`	não
`membership_id`	`bigint`	não

Chaves estrangeiras

(membership_id, user_id, tenant_id) → memberships (id, user_id, tenant_id) (mesmo tenant)
(run_id, tenant_id) → task_runs (run_id, tenant_id) (mesmo tenant)
user_id → users.id

Garantido pelo banco

Tipo	Nome	Definição
PK	`task_run_user_actors_pkey`	`PRIMARY KEY (run_id)`
Trigger	`task_run_user_actors_never_deleted`	recusa `DELETE` (e `UPDATE`, nas tabelas de origem e ator)
Trigger	`task_run_user_actors_no_truncate`	recusa `TRUNCATE`

Fora do banco

Nenhuma regra registrada além das constraints acima.

`task_run_events`

Trilha append-only de uma run de tenant: cada transição (queued, sent, started, retry_scheduled…), com tentativa, contagem de recebimentos e worker.

Coluna	Tipo	Nulo	Observação
`id`	`bigint`	não	identity (`GENERATED ALWAYS`)
`run_id`	`uuid`	não
`tenant_id`	`bigint`	não
`event`	`text`	não
`attempt`	`integer`	não
`receive_count`	`integer`	não	padrão `0`
`queue`	`text`	não
`worker_instance`	`text`	não
`error_code`	`text`	não	padrão `''`
`error_type`	`text`	não	padrão `''`
`detail`	`jsonb`	não	padrão `'{}'::jsonb`
`occurred_at`	`timestamptz`	não	padrão `clock_timestamp()`

Chaves estrangeiras

(run_id, tenant_id) → task_runs (run_id, tenant_id) (mesmo tenant)

Garantido pelo banco

Tipo	Nome	Definição
CHECK	`task_run_events_attempt_check`	`CHECK ((attempt >= 0))`
CHECK	`task_run_events_detail_check`	`CHECK (((jsonb_typeof(detail) = 'object') AND (octet_length((detail)::text) <= 2048)))`
CHECK	`task_run_events_event_check`	`CHECK ((event IN ('queued', 'sent', 'received', 'started', 'progress', 'retry_scheduled', 'succeeded', 'failed', 'skipped', 'dead_lettered', 'released_on_shutdown', 'redriven')))`
CHECK	`task_run_events_receive_count_check`	`CHECK ((receive_count >= 0))`
CHECK	`task_run_events_worker_instance_check`	`CHECK (((length(worker_instance) >= 1) AND (length(worker_instance) <= 128)))`
PK	`task_run_events_pkey`	`PRIMARY KEY (id)`
Trigger	`task_run_events_append_only`	trilha append-only: recusa `UPDATE` e `DELETE`
Trigger	`task_run_events_no_truncate`	recusa `TRUNCATE`

Fora do banco

Nenhuma regra registrada além das constraints acima.

`platform_task_runs`

Estado atual das runs sem tenant; o ator é system ou scheduler, e scheduler anda junto com trigger = 'schedule'.

Coluna	Tipo	Nulo	Observação
`run_id`	`uuid`	não
`name`	`text`	não
`queue`	`text`	não
`trigger`	`text`	não
`actor_kind`	`text`	não
`actor_label`	`text`	não
`correlation_id`	`uuid`	não
`causation_id`	`uuid`	não
`status`	`text`	não
`attempts`	`integer`	não	padrão `0`
`progress`	`smallint`	não	padrão `0`
`outcome`	`jsonb`	não	padrão `'{}'::jsonb`
`queued_at`	`timestamptz`	não	padrão `clock_timestamp()`
`started_at`	`timestamptz`	sim
`finished_at`	`timestamptz`	sim
`updated_at`	`timestamptz`	não	padrão `clock_timestamp()`

Chaves estrangeiras

nenhuma

Referenciada por: platform_task_run_events, platform_task_run_schedule_origins.

Garantido pelo banco

Tipo	Nome	Definição
CHECK	`platform_task_runs_actor_kind_check`	`CHECK ((actor_kind IN ('system', 'scheduler')))`
CHECK	`platform_task_runs_actor_label_check`	`CHECK (((length(actor_label) >= 1) AND (length(actor_label) <= 128)))`
CHECK	`platform_task_runs_attempts_check`	`CHECK ((attempts >= 0))`
CHECK	`platform_task_runs_check`	`CHECK (((actor_kind = 'scheduler') = (trigger = 'schedule')))`
CHECK	`platform_task_runs_check1`	`CHECK (((status IN ('succeeded', 'failed', 'skipped')) = (finished_at IS NOT NULL)))`
CHECK	`platform_task_runs_name_check`	`CHECK ((name ~ '^[a-z][a-z0-9._-]{1,63}$'))`
CHECK	`platform_task_runs_outcome_check`	`CHECK (((jsonb_typeof(outcome) = 'object') AND (octet_length((outcome)::text) <= 2048)))`
CHECK	`platform_task_runs_progress_check`	`CHECK (((progress >= 0) AND (progress <= 100)))`
CHECK	`platform_task_runs_queue_check`	`CHECK ((queue IN ('critical', 'default', 'bulk', 'maintenance')))`
CHECK	`platform_task_runs_status_check`	`CHECK ((status IN ('queued', 'running', 'retrying', 'succeeded', 'failed', 'skipped')))`
CHECK	`platform_task_runs_trigger_check`	`CHECK ((trigger IN ('dispatch', 'event', 'schedule', 'redrive')))`
PK	`platform_task_runs_pkey`	`PRIMARY KEY (run_id)`
Constraint trigger	`platform_task_runs_origin_present`	adiada até o commit (`DEFERRABLE INITIALLY DEFERRED`)
Trigger	`platform_task_runs_identity_fixed`	só colunas de ciclo de vida podem mudar
Trigger	`platform_task_runs_never_deleted`	recusa `DELETE` (e `UPDATE`, nas tabelas de origem e ator)
Trigger	`platform_task_runs_no_truncate`	recusa `TRUNCATE`

Fora do banco

Nenhuma regra registrada além das constraints acima.

`platform_task_run_schedule_origins`

Origem única de uma run agendada: nome do agendamento e horário previsto, únicos juntos.

Coluna	Tipo	Nulo
`run_id`	`uuid`	não
`schedule_name`	`text`	não
`execution_id`	`text`	não
`scheduled_for`	`timestamptz`	não

Chaves estrangeiras

run_id → platform_task_runs.run_id

Garantido pelo banco

Tipo	Nome	Definição
CHECK	`platform_task_run_schedule_origins_execution_id_check`	`CHECK (((length(execution_id) >= 1) AND (length(execution_id) <= 128)))`
PK	`platform_task_run_schedule_origins_pkey`	`PRIMARY KEY (run_id)`
UNIQUE	`platform_task_run_schedule_orig_schedule_name_scheduled_for_key`	`UNIQUE (schedule_name, scheduled_for)`
Trigger	`platform_task_run_schedule_origins_never_deleted`	recusa `DELETE` (e `UPDATE`, nas tabelas de origem e ator)
Trigger	`platform_task_run_schedule_origins_no_truncate`	recusa `TRUNCATE`

Fora do banco

Nenhuma regra registrada além das constraints acima.

`platform_task_run_events`

Trilha append-only das runs sem tenant.

Coluna	Tipo	Nulo	Observação
`id`	`bigint`	não	identity (`GENERATED ALWAYS`)
`run_id`	`uuid`	não
`event`	`text`	não
`attempt`	`integer`	não
`receive_count`	`integer`	não	padrão `0`
`queue`	`text`	não
`worker_instance`	`text`	não
`error_code`	`text`	não	padrão `''`
`error_type`	`text`	não	padrão `''`
`detail`	`jsonb`	não	padrão `'{}'::jsonb`
`occurred_at`	`timestamptz`	não	padrão `clock_timestamp()`

Chaves estrangeiras

run_id → platform_task_runs.run_id

Garantido pelo banco

Tipo	Nome	Definição
CHECK	`platform_task_run_events_attempt_check`	`CHECK ((attempt >= 0))`
CHECK	`platform_task_run_events_detail_check`	`CHECK (((jsonb_typeof(detail) = 'object') AND (octet_length((detail)::text) <= 2048)))`
CHECK	`platform_task_run_events_event_check`	`CHECK ((event IN ('queued', 'sent', 'received', 'started', 'progress', 'retry_scheduled', 'succeeded', 'failed', 'skipped', 'dead_lettered', 'released_on_shutdown', 'redriven')))`
CHECK	`platform_task_run_events_receive_count_check`	`CHECK ((receive_count >= 0))`
CHECK	`platform_task_run_events_worker_instance_check`	`CHECK (((length(worker_instance) >= 1) AND (length(worker_instance) <= 128)))`
PK	`platform_task_run_events_pkey`	`PRIMARY KEY (id)`
Trigger	`platform_task_run_events_append_only`	trilha append-only: recusa `UPDATE` e `DELETE`
Trigger	`platform_task_run_events_no_truncate`	recusa `TRUNCATE`

Fora do banco

Nenhuma regra registrada além das constraints acima.

Execuções e auditoria

Ciclo de vidaCopiar link

Status pela APICopiar link

TabelasCopiar link

task_runsCopiar link

task_run_user_actorsCopiar link

task_run_eventsCopiar link

platform_task_runsCopiar link

platform_task_run_schedule_originsCopiar link

platform_task_run_eventsCopiar link

Nesta página

Ciclo de vida

Status pela API

Tabelas

`task_runs`

`task_run_user_actors`

`task_run_events`

`platform_task_runs`

`platform_task_run_schedule_origins`

`platform_task_run_events`