# PHP API

Tudo em Queuety pode ser acessado pela classe estática `Queuety\Queuety`. Ela é o ponto de entrada único para despachar tarefas, criar fluxos de trabalho, controlar máquinas de estado, gerenciar filas e acessar subsistemas internos.

```php
use Queuety\Queuety;
```

## Acesso independente ao núcleo

O runtime de Queuety com suporte a DB pode ser inicializado fora do WordPress.

Esse caminho independente é destinado ao núcleo de orquestração:

- tarefas e workers (os pools de workers também precisam das constantes `DB_HOST`, `DB_NAME`, `DB_USER` e `DB_PASSWORD`; veja abaixo)
- fluxos de trabalho e sinais
- máquinas de estado e eventos
- artefatos, logs, métricas e agendamentos

Ele não substitui o adaptador WordPress. `Queuety::on_action()`,
`replace_wp_cron()`, a inicialização do plugin e o caminho de registro real de `wp queuety ...`
ainda exigem WordPress.

### `Queuety::init( Connection $conn )`

Inicialize Queuety com uma conexão direta com suporte a DB.

```php
use Queuety\Connection;
use Queuety\Queuety;

$conn = new Connection(
    host: '127.0.0.1:3306',
    dbname: 'wordpress',
    user: 'root',
    password: 'secret',
    prefix: 'wp_',
);

Queuety::init( $conn );
```

O argumento opcional `table_prefix` altera a parte Queuety dos nomes das tabelas do runtime por conexão:

```php
$conn = new Connection(
    host: '127.0.0.1:3306',
    dbname: 'wordpress',
    user: 'root',
    password: 'secret',
    prefix: 'wp_',
    table_prefix: 'themequeue_',
);
```

Isso resolve tabelas como `queuety_jobs` para `wp_themequeue_jobs`.

### `Queuety::ensure_schema()`

Garanta que as tabelas de runtime Queuety existam para a conexão ativa.

```php
Queuety::init( $conn );
Queuety::ensure_schema();
```

Para ver o modelo completo e o limite de WordPress, consulte [Uso independente](https://queuety.inline0.dev/pt/docs/features/standalone-use).

## Tarefas

### `Queuety::dispatch( $handler, $payload )`

Despacha uma tarefa. Aceita uma string com o nome do handler ou uma instância de `Contracts\Job`. Retorna um builder de `PendingJob` para encadear opções.

```php
// Handler name + payload (original API)
Queuety::dispatch( 'send_email', [ 'to' => 'user@example.com' ] );

// Contracts\Job instance (v0.6.0+)
Queuety::dispatch( new SendEmailJob( to: 'user@example.com' ) );

// With options
Queuety::dispatch( 'send_email', [ 'to' => 'user@example.com' ] )
    ->on_queue( 'emails' )
    ->with_priority( Priority::High )
    ->delay( 300 )
    ->max_attempts( 5 )
    ->rate_limit( 10, 60 )
    ->unique()
    ->after( $other_job_id );

// Get the job ID
$job_id = Queuety::dispatch( 'send_email', $payload )->id();
```

Quando uma instância de `Contracts\Job` é passada, o serializador extrai o FQCN como nome do handler e as propriedades públicas como payload. O parâmetro `$payload` é ignorado quando `$handler` é uma instância de `Job`.

### Métodos de `PendingJob`

| Método | Descrição |
|---|---|
| `on_queue( string $queue )` | Define a fila de destino |
| `with_priority( Priority $priority )` | Define o nível de prioridade |
| `delay( int $seconds )` | Atraso antes de a tarefa ficar disponível |
| `max_attempts( int $max )` | Número máximo de tentativas |
| `rate_limit( int $max, int $window )` | Limite de taxa: máximo de execuções por janela de segundos |
| `unique()` | Impede despachos duplicados |
| `after( int $job_id )` | Aguarda a conclusão de outra tarefa primeiro |
| `concurrency_group( string $group, int $limit )` | Coloca a tarefa em um grupo compartilhado de admissão de workers |
| `cost_units( int $units )` | Anexa metadados de custo relativo de execução ao despacho |
| `id()` | Força o despacho e retorna o ID da tarefa |

`concurrency_group()` e `cost_units()` alimentam o modelo mais amplo de [Gerenciamento de recursos](https://queuety.inline0.dev/pt/docs/features/resource-management), permitindo que o mesmo despacho participe de limites de concorrência baseados em contagem, orçamentos ponderados de fila ou provedor e heurísticas de admissão de workers.

### `Queuety::dispatch_sync( $handler, $payload )`

Executa uma tarefa de forma síncrona no processo atual, sem adicioná-la à fila.

```php
// With a Job instance
Queuety::dispatch_sync( new SendEmailJob( to: 'user@example.com', subject: 'Hi', body: 'Hello' ) );

// With a handler name and payload
Queuety::dispatch_sync( 'send_email', [ 'to' => 'user@example.com' ] );
```

O método `handle()` da tarefa é chamado diretamente. Nenhuma linha é criada no banco de dados, nenhum worker é envolvido e o middleware não é aplicado.

### `Queuety::batch( $jobs )`

Despacha várias tarefas em um único INSERT com várias linhas.

```php
$job_ids = Queuety::batch( [
    [ 'handler' => 'send_email', 'payload' => [ 'to' => 'a@example.com' ], 'queue' => 'emails' ],
    [ 'handler' => 'send_email', 'payload' => [ 'to' => 'b@example.com' ], 'priority' => 2 ],
] );
```

### `Queuety::create_batch( $jobs )`

Cria um `BatchBuilder` para despachar um grupo de tarefas com callbacks e acompanhamento do progresso. Consulte [Agrupamento](https://queuety.inline0.dev/pt/docs/features/batching) para ver todos os detalhes.

```php
$batch = Queuety::create_batch( [
    new ImportUsersJob( $chunk_1 ),
    new ImportUsersJob( $chunk_2 ),
] )
    ->name( 'Import users' )
    ->then( ImportCompleteHandler::class )
    ->catch( ImportFailedHandler::class )
    ->finally( ImportCleanupHandler::class )
    ->allow_failures()
    ->on_queue( 'imports' )
    ->dispatch();
```

### Métodos de `BatchBuilder`

| Método | Retorna | Descrição |
|---|---|---|
| `name( string $name )` | `self` | Define um nome para o lote |
| `on_queue( string $queue )` | `self` | Define a fila de todas as tarefas do lote |
| `then( string $handler_class )` | `self` | Handler chamado quando o lote é concluído com sucesso |
| `catch( string $handler_class )` | `self` | Handler chamado quando a primeira tarefa do lote falha |
| `finally( string $handler_class )` | `self` | Handler chamado quando o lote termina (com sucesso ou falha) |
| `allow_failures()` | `self` | Permite que o callback `then` seja executado mesmo em caso de falhas |
| `dispatch()` | `Batch` | Cria a linha do lote e todas as tarefas; retorna o objeto de valor `Batch` |

### `Queuety::find_batch( $id )`

Localiza um lote pelo ID. Retorna um objeto de valor `Batch` ou `null`.

```php
$batch = Queuety::find_batch( $batch_id );

if ( null !== $batch ) {
    echo $batch->progress() . '% complete';
}
```

## Controle de workers

### `Queuety::run_worker( $queue = 'default', $once = false )`

Executa diretamente o loop de um worker.

```php
Queuety::run_worker( 'default' );
Queuety::run_worker( 'critical,default', true );
```

### `Queuety::run_worker_pool( $workers, $queue = 'default' )`

Executa diretamente um pool de workers de tamanho fixo. Requer as extensões `pcntl` e `posix`. O pool lê as constantes WordPress `DB_HOST`, `DB_NAME`, `DB_USER` e `DB_PASSWORD` para as conexões filhas (somente os prefixos das tabelas vêm da conexão inicializada), então defina-as ao executar um pool fora do WordPress ([#5](https://github.com/inline0/queuety/issues/5)).

```php
Queuety::run_worker_pool( 4, 'providers' );
```

### `Queuety::run_auto_scaling_worker_pool( $min_workers, $max_workers, $queue = 'default' )`

Executa diretamente um pool adaptável de workers. Os requisitos são os mesmos de `run_worker_pool()`.

```php
Queuety::run_auto_scaling_worker_pool( 2, 6, 'providers' );
```

### Objeto de valor `Batch`

| Método/propriedade | Tipo | Descrição |
|---|---|---|
| `$id` | `int` | ID do lote |
| `$name` | `string\|null` | Nome opcional do lote |
| `$total_jobs` | `int` | Número total de tarefas no lote |
| `$pending_jobs` | `int` | Tarefas ainda pendentes |
| `$failed_jobs` | `int` | Número de tarefas com falha |
| `$failed_job_ids` | `array` | IDs das tarefas com falha |
| `$created_at` | `DateTimeImmutable` | Data de criação do lote |
| `$finished_at` | `DateTimeImmutable\|null` | Data de conclusão do lote |
| `$cancelled_at` | `DateTimeImmutable\|null` | Data de cancelamento do lote |
| `progress()` | `int` | Percentual de conclusão (0-100) |
| `finished()` | `bool` | Indica se o lote foi concluído |
| `has_failures()` | `bool` | Indica se alguma tarefa falhou |
| `cancelled()` | `bool` | Indica se o lote foi cancelado |

### `Queuety::chain( $jobs )`

Cria um `ChainBuilder` para executar tarefas em sequência. Cada tarefa depende da conclusão bem-sucedida da anterior.

```php
$first_job_id = Queuety::chain( [
    new FetchDataJob( $url ),
    new ProcessDataJob(),
    new NotifyCompleteJob(),
] )
    ->on_queue( 'pipeline' )
    ->catch( ChainFailedHandler::class )
    ->dispatch();
```

### Métodos de `ChainBuilder`

| Método | Retorna | Descrição |
|---|---|---|
| `on_queue( string $queue )` | `self` | Define a fila de todas as tarefas da cadeia |
| `catch( string $handler_class )` | `self` | Handler chamado quando qualquer tarefa da cadeia é enterrada permanentemente |
| `dispatch()` | `int` | Cria todas as tarefas com dependências sequenciais; retorna o ID da primeira tarefa |

### `Queuety::retry( $job_id )`

Tenta novamente uma tarefa específica. Redefine seu status para `pending`.

```php
Queuety::retry( 42 );
```

### `Queuety::retry_buried()`

Tenta novamente todas as tarefas enterradas. Retorna a quantidade de tarefas repetidas.

```php
$count = Queuety::retry_buried();
```

### `Queuety::purge( $older_than_days )`

Remove tarefas concluídas. Retorna a quantidade de tarefas removidas.

```php
$count = Queuety::purge();     // uses QUEUETY_RETENTION_DAYS
$count = Queuety::purge( 30 ); // purge jobs older than 30 days
```

## Filas

### `Queuety::stats( $queue )`

Obtém a contagem de tarefas agrupadas por status.

```php
$stats = Queuety::stats();          // all queues
$stats = Queuety::stats( 'emails' ); // specific queue
// ['pending' => 12, 'processing' => 3, 'completed' => 150, 'failed' => 2, 'buried' => 1]
```

### `Queuety::buried( $queue )`

Obtém todas as tarefas enterradas.

```php
$jobs = Queuety::buried();
$jobs = Queuety::buried( 'emails' );
```

### `Queuety::pause( $queue )`

Pausa uma fila para que os workers a ignorem.

```php
Queuety::pause( 'emails' );
```

### `Queuety::resume( $queue )`

Retoma uma fila pausada.

```php
Queuety::resume( 'emails' );
```

### `Queuety::is_paused( $queue )`

Verifica se uma fila está pausada.

```php
if ( Queuety::is_paused( 'emails' ) ) {
    // Queue is paused
}
```

## Fluxos de trabalho

### `Queuety::workflow( $name )`

Comece a criar um fluxo de trabalho. Retorna um `WorkflowBuilder`.

```php
$workflow_id = Queuety::workflow( 'generate_report' )
    ->then( FetchDataHandler::class )
    ->then( CallLLMHandler::class )
    ->then( FormatOutputHandler::class )
    ->dispatch( [ 'user_id' => 42 ] );
```

### Métodos de `WorkflowBuilder`

| Método | Descrição |
|---|---|
| `then( string $handler_class, ?string $name = null )` | Adiciona uma etapa sequencial. Nome opcional para ramificação condicional. |
| `parallel( array $handler_classes )` | Adiciona um grupo de etapas paralelas. |
| `for_each( string $items_key, string $handler_class, ?string $result_key = null, ForEachMode $mode = ForEachMode::All, ?int $quorum = null, ?string $reducer_class = null, ?string $name = null )` | Adiciona uma etapa dinâmica de iteração que expande uma tarefa por item no estado do fluxo de trabalho. |
| `repeat_while( string $target_step, ?string $state_key = null, mixed $expected = true, ?string $name = null, ?string $condition_class = null, ?int $max_iterations = null )` | Volta a uma etapa nomeada anterior enquanto uma chave de estado pública ou uma classe `RepeatCondition` corresponder. |
| `repeat_until( string $target_step, ?string $state_key = null, mixed $expected = true, ?string $name = null, ?string $condition_class = null, ?int $max_iterations = null )` | Volta a uma etapa nomeada anterior até que uma chave de estado pública ou uma classe `RepeatCondition` corresponda. |
| `run_workflow( string $workflow_name, WorkflowBuilder $sub_builder )` | Adiciona uma etapa de execução de fluxo de trabalho. |
| `delay( int $seconds = 0, int $minutes = 0, int $hours = 0, int $days = 0 )` | Adiciona uma etapa de espera durável. Todas as durações são somadas. |
| `wait_for_signal( string $name, ?string $result_key = null, ?string $step_name = null, array $match_payload = [], ?string $correlation_key = null )` | Adiciona uma etapa de espera por sinal. `match_payload` e `correlation_key` opcionais permitem ignorar eventos não relacionados. |
| `wait_for_signals( array $signal_names, WaitMode $mode = WaitMode::All, ?string $result_key = null, ?string $name = null, array $match_payload = [], ?string $correlation_key = null )` | Aguarda todos ou qualquer um de vários sinais, com correspondência opcional de conteúdo e correlação. |
| `wait_for_approval( string $signal_name = 'approval', ?string $result_key = 'approval', ?string $name = null, array $match_payload = [], ?string $correlation_key = null )` | Aguarda um sinal de aprovação humana. |
| `wait_for_decision( string $approve_signal = 'approved', string $reject_signal = 'rejected', ?string $result_key = 'decision', ?string $name = null, array $match_payload = [], ?string $correlation_key = null )` | Aguarda aprovação ou rejeição e armazena um conteúdo de decisão estruturado. |
| `wait_for_input( string $signal_name = 'input', ?string $result_key = 'input', ?string $name = null, array $match_payload = [], ?string $correlation_key = null )` | Aguarda um sinal de entrada humana. |
| `wait_for_workflow( int\|string $workflow, ?string $result_key = null, ?string $name = null )` | Aguarda a conclusão de um ID de fluxo de trabalho ou de um ID armazenado no estado público. |
| `wait_for_workflows( array\|string $workflows, WaitMode $mode = WaitMode::All, ?string $result_key = null, ?string $name = null, ?int $quorum = null )` | Aguarda a conclusão de todos, de qualquer um ou de um quórum de vários fluxos de trabalho. |
| `wait_for_workflow_group( string $group_key, WaitMode $mode = WaitMode::All, ?int $quorum = null, ?string $result_key = null, ?string $name = null )` | Aguarda um grupo de fluxos de trabalho iniciado anteriormente por chave interna do grupo. |
| `start_workflows( string $items_key, WorkflowBuilder $workflow_builder, string $result_key = 'started_workflow_ids', string $payload_key = 'item', bool $inherit_state = true, ?string $name = null, ?string $group_key = null )` | Inicia um fluxo de trabalho de nível superior por item de execução, com a opção de marcar o conjunto iniciado com uma chave de grupo durável. |
| `start_agents( string $items_key, WorkflowBuilder $workflow_builder, string $result_key = 'agent_workflow_ids', string $payload_key = 'agent_task', bool $inherit_state = true, ?string $name = null, ?string $group_key = null )` | Alias voltado a agentes para `start_workflows()`. |
| `wait_for_agents( array\|string $workflows = 'agent_workflow_ids', WaitMode $mode = WaitMode::All, ?string $result_key = 'agent_results', ?string $name = null, ?int $quorum = null )` | Alias voltado a agentes para `wait_for_workflows()`. |
| `wait_for_agent_group( string $group_key = 'agents', WaitMode $mode = WaitMode::All, ?int $quorum = null, ?string $result_key = 'agent_results', ?string $name = null )` | Alias voltado a agentes para `wait_for_workflow_group()`. |
| `version( string $version )` | Marca a definição do fluxo de trabalho com uma versão no nível da aplicação para inspeção e exportações. |
| `idempotency_key( string $key )` | Torna durável a iniciação do fluxo de trabalho para uma chave fornecida pelo chamador. Iniciá-lo novamente com a mesma chave retorna o ID original do fluxo de trabalho. |
| `max_transitions( int $max )` | Falha o fluxo de trabalho se mais de `$max` transições de etapa forem concluídas. |
| `max_for_each_items( int $max )` | Falha o fluxo de trabalho se uma etapa `for_each()` tentar expandir mais de `$max` itens. |
| `max_state_bytes( int $bytes )` | Falha o fluxo de trabalho se o estado público exceder `$bytes`. |
| `max_cost_units( int $max )` | Falha o fluxo de trabalho se as etapas concluídas consumirem mais de `$max` unidades de custo. |
| `max_started_workflows( int $max )` | Falha o fluxo de trabalho antes de iniciar mais de `$max` fluxos de trabalho filhos. |
| `compensate_with( string $handler_class )` | Anexa um manipulador de compensação à etapa adicionada mais recentemente. |
| `compensate_on_failure()` | Executa automaticamente as compensações das etapas concluídas quando o fluxo de trabalho falha. |
| `on_queue( string $queue )` | Define a fila de todas as etapas. |
| `with_priority( Priority $priority )` | Define a prioridade de todas as etapas. |
| `max_attempts( int $max )` | Define o número máximo de tentativas por etapa. |
| `on_cancel( string $handler_class )` | Registra uma classe de manipulador de limpeza para cancelamento. Consulte [Cancelamento](https://queuety.inline0.dev/pt/docs/workflows/cancellation). |
| `prune_state_after( int $steps = 2 )` | Ativa a poda automática do estado. Remove saídas de etapas mais antigas que o limite. Consulte [Poda do estado](https://queuety.inline0.dev/pt/docs/features/state-pruning). |
| `must_complete_within( int $seconds = 0, int $minutes = 0, int $hours = 0, int $days = 0 )` | Define um prazo para o fluxo de trabalho. Todas as durações são somadas. Consulte [Prazos](https://queuety.inline0.dev/pt/docs/workflows/deadlines). |
| `on_deadline( string $handler_class )` | Registra um manipulador chamado quando o prazo do fluxo de trabalho é excedido. Consulte [Prazos](https://queuety.inline0.dev/pt/docs/workflows/deadlines). |
| `dispatch( array $initial_payload = [] )` | Inicia o fluxo de trabalho. Retorna o ID do fluxo de trabalho. |

### `Queuety::workflow_status( $workflow_id )`

Obtém o status do fluxo de trabalho. Retorna um objeto `WorkflowState` ou `null`.

```php
$state = Queuety::workflow_status( $workflow_id );
echo $state->name;          // 'generate_report'
echo $state->status->value; // 'running'
echo $state->current_step;  // 1
echo $state->total_steps;   // 3
print_r( $state->state );   // accumulated public state array
echo $state->wait_type;     // 'signal' or 'workflow' while blocked
echo $state->wait_mode;     // 'all', 'any', or 'quorum'
echo $state->definition_version; // 'research.v2'
echo $state->definition_hash;    // '4c7a...'
echo $state->idempotency_key;    // 'brief:42:research'
echo $state->artifact_count;     // 2
print_r( $state->budget );       // configured workflow budget + current usage
print_r( $state->wait_details ); // matched/remaining blockers, result key, correlation info
print_r( $state->artifact_keys ); // ['draft', 'citations']
```

`WorkflowState` também expõe:

- `waiting_for`: os nomes dos sinais ou IDs dos fluxos de trabalho que estão bloqueando a execução
- `current_step_name`: o nome configurado da etapa atual, se houver
- `wait_mode`: o modo de espera atual (`all`, `any` ou `quorum`) enquanto bloqueado
- `wait_details`: dados adicionais de inspeção, como bloqueadores correspondentes e restantes
- `definition_version`: o valor definido por `version()`, se houver
- `definition_hash`: um hash determinístico da definição do fluxo de trabalho
- `idempotency_key`: a chave durável de iniciação, se houver
- `budget`: limites configurados e uso atual, se as proteções estiverem ativadas
- `artifact_count`: número de artefatos armazenados para o fluxo de trabalho
- `artifact_keys`: chaves dos artefatos armazenados para inspeção rápida

### `Queuety::retry_workflow( $workflow_id )`

Tenta novamente um fluxo de trabalho com falha a partir da etapa que falhou.

```php
Queuety::retry_workflow( $workflow_id );
```

Lança `RuntimeException` se o fluxo de trabalho já tiver sido compensado após uma falha.

### `Queuety::pause_workflow( $workflow_id )`

Pausa um fluxo de trabalho em execução. O trabalho já enfileirado para a etapa atual ainda pode terminar, mas as etapas seguintes não serão enfileiradas até que o fluxo de trabalho seja retomado.

```php
Queuety::pause_workflow( $workflow_id );
```

### `Queuety::resume_workflow( $workflow_id )`

Retoma um fluxo de trabalho pausado.

```php
Queuety::resume_workflow( $workflow_id );
```

### `Queuety::cancel_workflow( $workflow_id )`

Cancela um fluxo de trabalho e executa os manipuladores de limpeza registrados. Define o status como `cancelled` e enterra todos os trabalhos pendentes e em processamento do fluxo de trabalho.

```php
Queuety::cancel_workflow( $workflow_id );
```

Lança `RuntimeException` se o fluxo de trabalho já estiver `completed` ou `cancelled`. Consulte [Cancelamento](https://queuety.inline0.dev/pt/docs/workflows/cancellation) para obter detalhes.

### `Queuety::rewind_workflow( $workflow_id, $to_step )`

Retrocede um fluxo de trabalho até uma etapa anterior e o reexecuta a partir dali. O estado é restaurado do registro de eventos `state_after` da etapa indicada, e a próxima etapa é enfileirada.

```php
Queuety::rewind_workflow( $workflow_id, to_step: 1 );
```

Lança `RuntimeException` se não houver estado registrado para a etapa de destino. Requer o [Registro de eventos do fluxo de trabalho](https://queuety.inline0.dev/pt/docs/workflows/event-log). Consulte [Viagem no tempo](https://queuety.inline0.dev/pt/docs/workflows/time-travel) para obter detalhes.

### `Queuety::fork_workflow( $workflow_id )`

Cria uma ramificação de um fluxo de trabalho em execução como cópia independente no estado atual. Retorna o novo ID do fluxo de trabalho.

```php
$forked_id = Queuety::fork_workflow( $workflow_id );
```

O fluxo de trabalho ramificado recebe seu próprio ID e opera independentemente do original. Consulte [Ramificações](https://queuety.inline0.dev/pt/docs/workflows/forking) para obter detalhes.

### `Queuety::export_workflow( $workflow_id )`

Exporta o histórico completo de execução de um fluxo de trabalho como um array serializável em JSON. Inclui a linha do fluxo de trabalho, todos os trabalhos, eventos do fluxo de trabalho e entradas de registro.

```php
$data = Queuety::export_workflow( $workflow_id );
```

Consulte [Exportação e reprodução](https://queuety.inline0.dev/pt/docs/workflows/export-replay) para conhecer a estrutura JSON e os casos de uso.

### `Queuety::replay_workflow( $data )`

Reproduz um fluxo de trabalho exportado no ambiente atual. Cria um novo fluxo de trabalho a partir dos dados exportados e retorna o novo ID do fluxo de trabalho.

```php
$new_id = Queuety::replay_workflow( $data );
```

Consulte [Exportação e reprodução](https://queuety.inline0.dev/pt/docs/workflows/export-replay) para obter detalhes.

### `Queuety::replace_wp_cron()`

Substitui o sistema integrado de WordPress cron pelo agendador de Queuety. Intercepta `wp_schedule_event()`, `wp_unschedule_event()` e `wp_get_scheduled_event()` e encaminha eventos recorrentes pelo worker Queuety.

```php
Queuety::replace_wp_cron();
```

Só funciona quando WordPress está carregado. Consulte [WP-Cron Substituição](https://queuety.inline0.dev/pt/docs/features/wp-cron) para obter detalhes.

### `Queuety::restore_wp_cron()`

Restaura o comportamento padrão de WordPress cron removendo os hooks de integração de Queuety cron.

```php
Queuety::restore_wp_cron();
```

Consulte [WP-Cron Substituição](https://queuety.inline0.dev/pt/docs/features/wp-cron) para conhecer as limitações.

### `Queuety::signal( $workflow_id, $name, $data )`

Envia um sinal para um fluxo de trabalho. Se o fluxo estiver aguardando esse sinal, ele será retomado imediatamente. Caso contrário, o sinal será armazenado e processado quando o fluxo de trabalho chegar à etapa `wait_for_signal` correspondente.

```php
Queuety::signal( $workflow_id, 'approved' );

// With data merged into workflow state
Queuety::signal( $workflow_id, 'approved', [
    'approved_by' => 'admin@example.com',
] );
```

Consulte [Sinais de fluxo de trabalho](https://queuety.inline0.dev/pt/docs/workflows/signals) para obter detalhes.

### `Queuety::approve_workflow( $workflow_id, $data = [], $signal_name = 'approval' )`

Wrapper semântico em torno de `signal()` para fluxos de aprovação.

```php
Queuety::approve_workflow( $workflow_id, [
    'reviewer' => 'editor@example.com',
] );
```

### `Queuety::reject_workflow( $workflow_id, $data = [], $signal_name = 'rejected' )`

Wrapper semântico em torno de `signal()` para fluxos de rejeição.

```php
Queuety::reject_workflow( $workflow_id, [
    'reason' => 'needs citations',
] );
```

### `Queuety::submit_workflow_input( $workflow_id, $data = [], $signal_name = 'input' )`

Wrapper semântico em torno de `signal()` para entrada humana estruturada.

```php
Queuety::submit_workflow_input( $workflow_id, [
    'notes' => 'Ship after legal review',
] );
```

### `Queuety::put_artifact( $workflow_id, $artifact_key, $content, $kind = 'json', $step_index = null, $metadata = [] )`

Armazena um artefato durável para um fluxo de trabalho.

```php
Queuety::put_artifact(
    $workflow_id,
    'research_brief',
    [ 'summary' => 'done' ],
    'json',
    metadata: [ 'source' => 'agent' ],
);
```

### `Queuety::put_current_artifact( $artifact_key, $content, $kind = 'json', $metadata = [] )`

Armazena um artefato para a etapa do fluxo de trabalho em execução.

```php
Queuety::put_current_artifact(
    'draft',
    [ 'status' => 'ready' ],
    'json',
);
```

### `Queuety::workflow_artifact( $workflow_id, $artifact_key )`

Busca um artefato armazenado para um fluxo de trabalho.

```php
$artifact = Queuety::workflow_artifact( $workflow_id, 'draft' );
```

### `Queuety::workflow_artifacts( $workflow_id, $include_content = false )`

Lista os artefatos de um fluxo de trabalho.

```php
$artifacts = Queuety::workflow_artifacts( $workflow_id );
```

### `Queuety::delete_workflow_artifact( $workflow_id, $artifact_key )`

Exclui um artefato de um fluxo de trabalho.

```php
Queuety::delete_workflow_artifact( $workflow_id, 'draft' );
```

## Máquinas de estado

### `Queuety::machine( $name )`

Comece a criar uma máquina de estado. Retorna um `StateMachineBuilder`.

```php
use Queuety\Enums\StateMachineStatus;

$machine_id = Queuety::machine( 'agent_session' )
    ->state( 'awaiting_user' )
    ->on( 'user_message', 'planning' )
    ->state( 'planning' )
    ->action( PlanSessionAction::class )
    ->on( 'planned', 'completed' )
    ->state( 'completed', StateMachineStatus::Completed )
    ->dispatch( [ 'thread_id' => 42 ] );
```

### Métodos de `StateMachineBuilder`

| Método | Descrição |
|---|---|
| `initial( string $state_name )` | Define explicitamente o estado inicial. |
| `state( string $state_name, ?StateMachineStatus $terminal_status = null )` | Começa a configurar um estado. |
| `action( string\|array $action_class )` | Registra uma ação de entrada enfileirada para o estado atual. Passe um nome de classe ou uma definição estruturada com `class`, `payload` e `config`; `payload` chega a `StateAction::handle()` como `$payload`. |
| `on( string $event, string $target, string\|array\|null $guard_class = null, ?string $name = null )` | Registra uma transição de evento a partir do estado atual. A condição aceita o mesmo formato estruturado de `action()`. |
| `on_queue( string $queue )` | Define a fila usada para ações de estado enfileiradas. |
| `with_priority( Priority $priority )` | Define a prioridade das ações de estado enfileiradas. |
| `max_attempts( int $max_attempts )` | Define o limite de tentativas para ações de estado enfileiradas. |
| `version( string $version )` | Marca a definição da máquina com uma versão no nível da aplicação. |
| `idempotency_key( string $key )` | Torna durável a iniciação para uma chave fornecida pelo chamador. Iniciá-la novamente com a mesma chave retorna o ID original da máquina. |
| `dispatch( array $initial_state = [] )` | Inicia a máquina e retorna o ID da máquina. |

As classes de ação de entrada de estado também podem expor um método opcional `config()` com as mesmas chaves de política de recursos compatíveis com as etapas do fluxo de trabalho: `concurrency_group`, `concurrency_limit` e `cost_units`.

### `Queuety::dispatch_state_machine_definition( $definition, $initial_state = [], $options = [] )`

Inicia um pacote serializado de definição de máquina de estado. A maioria do código da aplicação deve preferir `machine()->dispatch()`. Este método de nível inferior existe para que adaptadores possam iniciar uma máquina sem depender diretamente do construtor.

```php
$machine_id = Queuety::dispatch_state_machine_definition(
    $definition,
    [ 'thread_id' => 42 ],
    [ 'idempotency_key' => 'thread:42' ],
);
```

### `Queuety::machine_status( $machine_id )`

Obtém o status atual da máquina. Retorna um objeto `StateMachineState` ou `null`.

```php
$status = Queuety::machine_status( $machine_id );

echo $status->name;               // 'agent_session'
echo $status->status->value;      // 'waiting_event'
echo $status->current_state;      // 'awaiting_review'
print_r( $status->state );        // public machine state
print_r( $status->available_events ); // valid incoming events in the current state
```

`StateMachineState` também expõe:

- `definition_version`
- `definition_hash`
- `idempotency_key`
- `error_message`
- `current_action`
- `terminal_status`

### `Queuety::machine_event( $machine_id, $event_name, $payload = [] )`

Envia um evento externo para uma máquina em espera.

```php
Queuety::machine_event(
    $machine_id,
    'approve',
    [
        'approved' => true,
        'reviewer' => 'editor@example.com',
    ]
);
```

O conteúdo fica disponível para as condições de transição e é mesclado ao estado público da máquina quando o evento é aceito.

### `Queuety::list_machines( $limit = 50, $status = null )`

Lista os registros persistidos da máquina para inspeção.

```php
$machines = Queuety::list_machines();
$waiting  = Queuety::list_machines( status: 'waiting_event' );
```

Cada linha inclui o ID da máquina, o nome, o status, o estado atual, a versão
da definição, o hash da definição, a chave de idempotência e os registros de data e hora do ciclo de vida.

### `Queuety::machine_timeline( $machine_id, $limit = 100, $offset = 0 )`

Obtém a linha do tempo durável de eventos de uma máquina.

```php
$timeline = Queuety::machine_timeline( $machine_id );
$page_two = Queuety::machine_timeline( $machine_id, 100, 100 );
```

Cada linha de evento contém: `id`, `machine_id`, `job_id`, `state_name`, `handler`, `event`, `event_name`, `transition_name`, `queue`, `attempt`, `input`, `output`, `state_before`, `state_after`, `context`, `artifacts`, `chunks`, `error`, `duration_ms` e `created_at`.

### `Queuety::machine_trace( $machine_id )`

Obtém um pacote de rastreamento normalizado para um depurador de máquinas de estado UI.

```php
$trace = Queuety::machine_trace( $machine_id );
```

O rastreamento contém `machine`, `states` agrupados, `events` brutos, ação correlacionada `jobs`, `logs`, `artifacts` e `chunks`.

### `Queuety::machine_state_at( $machine_id, $event_id )`

Obtém o estado público após um evento específico do rastreamento da máquina, ou `null` se não for encontrado.

```php
$state = Queuety::machine_state_at( $machine_id, $event_id );
```

Consulte [Máquinas de estado](https://queuety.inline0.dev/pt/docs/state-machines) para conhecer o modelo do ciclo de vida e os padrões de uso.

## Modelos de fluxo de trabalho

### `Queuety::define_workflow( $name )`

Cria um construtor de fluxo de trabalho para usar como modelo.

```php
$builder = Queuety::define_workflow( 'onboarding' )
    ->then( CreateAccountHandler::class )
    ->then( SendWelcomeEmailHandler::class );
```

### `Queuety::register_workflow_template( $builder )`

Registra um modelo de fluxo de trabalho.

```php
Queuety::register_workflow_template( $builder );
```

### `Queuety::run_workflow( $name, $payload, $options = [] )`

Inicia um modelo de fluxo de trabalho registrado pelo nome. Retorna o ID do fluxo de trabalho.

```php
$workflow_id = Queuety::run_workflow( 'onboarding', [ 'email' => 'user@example.com' ] );

$workflow_id = Queuety::run_workflow(
    'onboarding',
    [ 'email' => 'user@example.com' ],
    [ 'idempotency_key' => 'onboarding:user@example.com' ],
);
```

Lança `RuntimeException` se o modelo não estiver registrado.

### `Queuety::dispatch_workflow_definition( $definition, $payload, $options = [] )`

Inicia um fluxo de trabalho a partir de um pacote de definição em tempo de execução.

A maioria do código da aplicação deve preferir `run_workflow()` ou `workflow()->dispatch()`. Este método de nível inferior existe para que adaptadores reutilizáveis possam iniciar uma definição serializada de fluxo de trabalho sem depender de métodos internos do gerenciador de fluxos de trabalho.

```php
$workflow_id = Queuety::dispatch_workflow_definition(
    $definition,
    [ 'email' => 'user@example.com' ],
    [ 'idempotency_key' => 'onboarding:user@example.com' ],
);
```

### `Queuety::on_action( $hook, $workflow, $map = null, $when = null, $idempotency_key = null, $priority = 10, $accepted_args = null )`

Registra uma ação WordPress que inicia um fluxo de trabalho.

```php
Queuety::on_action(
    'save_post',
    workflow: 'content_review',
    map: static fn ( int $post_id, object $post, bool $update ): array => [
        'post_id' => $post_id,
        'post_type' => $post->post_type,
        'update' => $update,
    ],
    when: static fn ( int $post_id, object $post ): bool => 'post' === $post->post_type,
    idempotency_key: static fn ( int $post_id ): string => "save_post:{$post_id}",
);
```

`$workflow` pode ser:

- o nome de um modelo de fluxo de trabalho registrado
- um `WorkflowBuilder` em linha

`map`, `when` e `idempotency_key` são executados de forma síncrona dentro da solicitação atual de WordPress. Somente as etapas do fluxo de trabalho são executadas de forma assíncrona após a iniciação.

Consulte [Gatilhos de ação](https://queuety.inline0.dev/pt/docs/features/action-triggers) para ver o guia completo.

### `Queuety::workflow_templates()`

Obtém o registro de modelos de fluxo de trabalho.

```php
$registry = Queuety::workflow_templates();
$template = $registry->get( 'onboarding' ); // WorkflowTemplate or null
```

### `Queuety::load_workflows( $directory, $recursive )`

Carrega e registra todos os arquivos de fluxo de trabalho de um diretório. Cada arquivo `.php` deve retornar um `WorkflowBuilder`. Retorna o número de fluxos de trabalho registrados.

```php
$count = Queuety::load_workflows( __DIR__ . '/workflows/' );
$count = Queuety::load_workflows( __DIR__ . '/workflows/', recursive: true );
```

### `Queuety::load_workflow_file( $file_path )`

Carrega e registra um único arquivo de fluxo de trabalho. Retorna o `WorkflowTemplate` ou `null` se o arquivo não retornar um construtor.

```php
$template = Queuety::load_workflow_file( __DIR__ . '/workflows/onboard-user.php' );
```

## Agendamento

### `Queuety::schedule( $handler, $payload )`

Cria um agendamento recorrente. Retorna um construtor `PendingSchedule`.

```php
Queuety::schedule( 'cleanup_handler' )
    ->every( '1 hour' )
    ->on_queue( 'maintenance' );

Queuety::schedule( 'nightly_report' )
    ->cron( '0 3 * * *' )
    ->on_queue( 'reports' );
```

### Métodos de `PendingSchedule`

| Método | Descrição |
|---|---|
| `every( string $interval )` | Define uma expressão de intervalo (e.g. `1 hour`, `30 minutes`) |
| `cron( string $expression )` | Define uma expressão cron de 5 campos |
| `overlap( OverlapPolicy $policy )` | Define a política de sobreposição (padrão: `Allow`). Consulte [Agendamento](https://queuety.inline0.dev/pt/docs/features/scheduling). |
| `on_queue( string $queue )` | Define a fila de destino (padrão: `default`) |
| `id()` | Força a iniciação e retorna o ID do agendamento |

### `Queuety::scheduler()`

Obtém a instância interna de `Scheduler`.

```php
$scheduler = Queuety::scheduler();
$schedules = $scheduler->list();
$scheduler->remove( 'handler_name' );
$count = $scheduler->tick(); // manually trigger
```

## Registro de manipuladores

### `Queuety::register( $name, $class )`

Registra uma classe de manipulador sob um nome.

```php
Queuety::register( 'send_email', SendEmailHandler::class );
```

### `Queuety::discover_handlers( $directory, $namespace )`

Descobre automaticamente e registra classes de manipulador de um diretório. Retorna o número de manipuladores registrados.

```php
$count = Queuety::discover_handlers( __DIR__ . '/handlers', 'MyPlugin\\Handlers' );
```

### `Queuety::registry()`

Obtém o registro de manipuladores.

```php
$registry = Queuety::registry();
```

## Observabilidade

### `Queuety::logger()`

Obtém a instância de `Logger` para consultar entradas de registro.

```php
$logger = Queuety::logger();
$logs   = $logger->for_job( 42 );
$logs   = $logger->for_workflow( 7 );
$logs   = $logger->for_handler( 'send_email', 50 );
$logs   = $logger->for_event( LogEvent::Failed, 50 );
$logs   = $logger->since( new \DateTimeImmutable( '-1 hour' ), 100 );
$count  = $logger->purge( 30 );
```

### `Queuety::metrics()`

Obtém a instância de `Metrics`.

```php
$stats = Queuety::metrics()->handler_stats( 60 ); // last 60 minutes
```

### `Queuety::webhook_notifier()`

Obtém a instância de `WebhookNotifier`.

```php
$notifier = Queuety::webhook_notifier();
$id       = $notifier->register( 'job.buried', 'https://hooks.slack.com/...' );
$webhooks = $notifier->list();
$notifier->remove( $id );
```

### `Queuety::rate_limiter()`

Obtém a instância de `RateLimiter`.

```php
$limiter = Queuety::rate_limiter();
$limiter->register( 'call_openai', 60, 60 );
```

## Cache

### `Queuety::cache()`

Obtém a instância do backend de cache ativo.

```php
$cache = Queuety::cache();
$cache->set( 'my_key', 'my_value', 60 );
$value = $cache->get( 'my_key' );
```

### `Queuety::set_cache( $cache )`

Substitui o backend de cache. Chame antes de `Queuety::init()` para usar uma implementação personalizada.

```php
Queuety::set_cache( new RedisCache() );
Queuety::init( $connection );
```

### `QUEUETY_CACHE_TTL`

TTL padrão do cache em segundos (padrão: `5`). Defina essa constante em `wp-config.php` para alterar o TTL padrão usado pelas operações internas de cache.

```php
define( 'QUEUETY_CACHE_TTL', 10 );
```

Consulte [Armazenamento em cache](https://queuety.inline0.dev/pt/docs/features/caching) para obter detalhes sobre backends e detecção automática.

## Registro de eventos da máquina de estado

### `Queuety::machine_events()`

Obtém a instância de `StateMachineEventLog`.

```php
$log = Queuety::machine_events();
```

## Registro de eventos do fluxo de trabalho

### `Queuety::workflow_events()`

Obtém a instância de `WorkflowEventLog`.

```php
$log = Queuety::workflow_events();
```

### `Queuety::workflow_timeline( $workflow_id, $limit = 100, $offset = 0 )`

Obtém a linha do tempo completa dos eventos de um fluxo de trabalho. Retorna um array de linhas de evento ordenadas por ID.

```php
$events = Queuety::workflow_timeline( $workflow_id );
$next   = Queuety::workflow_timeline( $workflow_id, 100, 100 );
```

Cada linha de evento contém: `id`, `workflow_id`, `job_id`, `parent_event_id`, `step_index`, `step_name`, `step_type`, `handler`, `event`, `queue`, `attempt`, `input`, `output`, `state_before`, `state_after`, `context`, `artifacts`, `chunks`, `error`, `error_message` (copiado de `error.message`), `duration_ms` e `created_at`.

### `Queuety::workflow_trace( $workflow_id )`

Obtenha um pacote de rastreamento normalizado para um depurador de fluxos de trabalho UI.

```php
$trace = Queuety::workflow_trace( $workflow_id );
```

O rastreamento contém `workflow`, agrupados `steps`, brutos `events`, `jobs`, `logs`, `artifacts`, `chunks`, `signals` e `wait_dependencies`.

### `Queuety::trace_input( $input )`

Defina a entrada no nível da aplicação para a etapa do fluxo de trabalho em execução no momento.

### `Queuety::trace_output( $output )`

Defina a saída no nível da aplicação para a etapa do fluxo de trabalho em execução no momento.

### `Queuety::trace_context( array $context )`

Mescle o contexto no nível da aplicação à etapa do fluxo de trabalho em execução no momento.

### `Queuety::workflow_state_at( $workflow_id, $step_index )`

Obtenha o estado público após a conclusão ou retomada de uma etapa específica do fluxo de trabalho, ou `null` se não for encontrado.

```php
$state = Queuety::workflow_state_at( $workflow_id, 2 );
```

Consulte [Log de eventos do fluxo de trabalho](https://queuety.inline0.dev/pt/docs/workflows/event-log) para ver casos de uso e comandos CLI.

## Instâncias internas

Estes métodos retornam instâncias internas para casos de uso avançados.

| Método | Retorna | Descrição |
|---|---|---|
| `Queuety::queue()` | `Queue` | Operações de fila (reivindicar, liberar, enterrar) |
| `Queuety::worker()` | `Worker` | Controle do processo do worker |
| `Queuety::workflow_manager()` | `Workflow` | Orquestração de fluxos de trabalho |
| `Queuety::machines()` | `StateMachine` | Gerenciamento do ciclo de vida da máquina de estados |
| `Queuety::connection()` | `Connection` | Conexão com o banco de dados |
| `Queuety::batch_manager()` | `BatchManager` | Gerenciamento do ciclo de vida de lotes (cancelar, podar) |
| `Queuety::chunk_store()` | `ChunkStore` | Persistência de partes para etapas de streaming |
| `Queuety::machine_events()` | `StateMachineEventLog` | Eventos de rastreamento de máquinas de estados e pacotes de rastreamento normalizados |
| `Queuety::workflow_events()` | `WorkflowEventLog` | Eventos de rastreamento de fluxos de trabalho e pacotes de rastreamento normalizados |
| `Queuety::resource_manager()` | `ResourceManager` | Perfis de admissão de workers, orçamentos ponderados e inspeção da memória do sistema |
| `Queuety::cache()` | `Cache` | Instância do backend de cache |

## Testes

### `Queuety::fake()`

Substitua a fila por um objeto falso em memória para testes. Retorna uma instância `QueueFake` que registra os trabalhos enviados sem acessar o banco de dados. `create_batch()` também registra metadados falsos de lote; as cadeias são verificadas por meio dos trabalhos individuais enviados por elas.

```php
$fake = Queuety::fake();
SendEmailJob::dispatch( 'user@example.com', 'Hello', 'Hi!' );
$fake->assert_pushed( SendEmailJob::class );
```

### `Queuety::reset()`

Redefina todo o estado interno, incluindo o objeto falso da fila. Chame dentro de `tearDown()`.

```php
Queuety::reset();
```

### Métodos de `QueueFake`

| Método | Descrição |
|---|---|
| `assert_pushed( string $class, ?Closure $callback )` | Verifica se uma classe de trabalho foi enviada. Um callback opcional filtra os dados do trabalho. |
| `assert_pushed_times( string $class, int $count )` | Verifica se um trabalho foi enviado exatamente N vezes. |
| `assert_not_pushed( string $class )` | Verifica se um trabalho nunca foi enviado. |
| `assert_nothing_pushed()` | Verifica se nenhum trabalho foi enviado. |
| `assert_batched( ?Closure $callback )` | Verifica se um lote foi despachado. Um callback opcional filtra os dados do lote. |
| `pushed( string $class )` | Obtém todos os despachos registrados para uma classe. Retorna uma matriz. |
| `batches()` | Obtém todos os lotes registrados. Retorna uma matriz. |
| `reset()` | Limpa todos os trabalhos e lotes registrados. |

Consulte [Testes](https://queuety.inline0.dev/pt/docs/features/testing) para ver exemplos completos.

## Interfaces

### `Handler`

Interface para manipuladores de trabalhos simples.

```php
interface Handler {
    public function handle( array $payload ): void;
    public function config(): array;
}
```

`config()` pode retornar `queue`, `max_attempts`, `backoff`, `rate_limit`, `concurrency_group`, `concurrency_limit` e `cost_units`.

### `Step`

Interface para manipuladores de etapas do fluxo de trabalho.

```php
interface Step {
    public function handle( array $state ): array;
    public function config(): array;
}
```

`config()` pode retornar `max_attempts`, `backoff`, `concurrency_group`, `concurrency_limit` e `cost_units`.

### `Contracts\ForEachHandler`

Interface para manipuladores dinâmicos de ramificações for-each.

```php
namespace Queuety\Contracts;

interface ForEachHandler {
    public function handle_item( array $state, mixed $item, int $index ): array;
    public function config(): array;
}
```

`config()` pode retornar `max_attempts`, `backoff`, `rate_limit`, `concurrency_group`, `concurrency_limit` e `cost_units`.

### `Contracts\ForEachReducer`

Redutor opcional para resultados de for-each.

```php
namespace Queuety\Contracts;

interface ForEachReducer {
    public function reduce( array $state, array $for_each ): array;
}
```

### `Contracts\Compensation`

Interface para manipuladores de compensação de etapas.

```php
namespace Queuety\Contracts;

interface Compensation {
    public function handle( array $state ): void;
}
```

### `Contracts\RepeatCondition`

Interface para predicados de loop usados por `repeat_until()` e `repeat_while()` quando uma comparação de chave de estado é muito limitada.

```php
namespace Queuety\Contracts;

interface RepeatCondition {
    public function matches( array $state ): bool;
}
```

### `Contracts\StateAction`

Interface para ações enfileiradas de entrada de estado.

```php
namespace Queuety\Contracts;

interface StateAction {
    public function handle( array $state, ?string $event = null, array $event_payload = [], array $payload = [] ): array|string;
}
```

`$payload` recebe o `payload` estruturado da definição da ação, se a máquina tiver sido definida com um. Retorne atualizações do estado público. Inclua `_event` e, opcionalmente, `_event_payload` quando a ação deve fazer a transição imediatamente.

As ações de estado também podem definir um método `config()` opcional. Queuety lê `concurrency_group`, `concurrency_limit` e `cost_units` dele quando a ação de entrada é enfileirada.

### `Contracts\StateGuard`

Interface para proteções de transição de máquinas de estados.

```php
namespace Queuety\Contracts;

interface StateGuard {
    public function allows( array $state, array $event_payload, string $event, array $payload = [] ): bool;
}
```

### `Contracts\Job`

Interface para classes de trabalho independentes que podem ser despachadas. As classes de trabalho encapsulam a carga útil como propriedades públicas e a lógica de execução em `handle()`.

```php
namespace Queuety\Contracts;

interface Job {
    public function handle(): void;
}
```

As classes de trabalho podem definir opcionalmente um método `middleware()` que retorna uma matriz de instâncias `Contracts\Middleware`.

### `Contracts\Cache`

Interface para backends de cache. Consulte [Armazenamento em cache](https://queuety.inline0.dev/pt/docs/features/caching) para ver implementações integradas e backends personalizados.

```php
namespace Queuety\Contracts;

interface Cache {
    public function get( string $key ): mixed;
    public function set( string $key, mixed $value, int $ttl = 0 ): void;
    public function delete( string $key ): void;
    public function has( string $key ): bool;
    public function add( string $key, mixed $value, int $ttl = 0 ): bool;
    public function flush(): void;
}
```

| Método | Retorna | Descrição |
|---|---|---|
| `get( $key )` | `mixed` | Recupera um valor. Retorna `null` se não for encontrado ou tiver expirado. |
| `set( $key, $value, $ttl )` | `void` | Armazena um valor. TTL de 0 significa que não expira. |
| `delete( $key )` | `void` | Remove um valor. |
| `has( $key )` | `bool` | Verifica se uma chave existe e não expirou. |
| `add( $key, $value, $ttl )` | `bool` | Definição atômica somente se não existir. Retorna `true` se o valor for definido. |
| `flush()` | `void` | Remove todos os itens do cache. |

### `WorkflowEventLog`

Registra transições de etapas do fluxo de trabalho com o contexto completo do rastreamento. Acesse por meio de `Queuety::workflow_events()`.

| Método | Retorna | Descrição |
|---|---|---|
| `record_event( array $event )` | `void` | Registra um evento de rastreamento bruto |
| `record_step_started( ... )` | `void` | Registra um evento step_started com a entrada e o estado antes da execução |
| `record_step_completed( ... )` | `void` | Registra um evento step_completed com a entrada, a saída, o estado anterior e o estado posterior |
| `record_step_failed( ... )` | `void` | Registra um evento step_failed com o contexto do rastreamento e detalhes estruturados do erro |
| `get_timeline( int $workflow_id, ?int $limit = 100, int $offset = 0 )` | `array` | Obtém os eventos de rastreamento do fluxo de trabalho em ordem, com paginação opcional |
| `get_trace( int $workflow_id )` | `array` | Obtém um pacote de rastreamento normalizado |
| `get_state_at_step( int $workflow_id, int $step_index )` | `array\|null` | Obtém o estado público após a conclusão ou retomada de uma etapa específica |
| `prune( int $older_than_days )` | `int` | Exclui eventos anteriores ao número de dias indicado. Retorna o número de linhas excluídas. |

### `StateMachineEventLog`

Registra eventos do ciclo de vida da máquina de estados, ações, transições e proteções com os mesmos campos de rastreamento dos eventos do fluxo de trabalho.

| Método | Retorna | Descrição |
|---|---|---|
| `record_event( array $event )` | `void` | Registra um evento bruto de rastreamento da máquina |
| `get_timeline( int $machine_id, ?int $limit = 100, int $offset = 0 )` | `array` | Obtém os eventos de rastreamento da máquina em ordem, com paginação opcional |
| `get_trace( int $machine_id )` | `array` | Obtém um pacote normalizado de rastreamento da máquina |
| `get_state_at_event( int $machine_id, int $event_id )` | `array\|null` | Obtém o estado público após um evento específico de rastreamento da máquina |
| `prune( int $older_than_days )` | `int` | Exclui eventos anteriores ao número de dias indicado. Retorna o número de linhas excluídas. |

### `Contracts\StreamingStep`

Interface para manipuladores de etapas do fluxo de trabalho que produzem um fluxo de partes. Cada valor produzido é persistido imediatamente no banco de dados. Consulte [Etapas de streaming](https://queuety.inline0.dev/pt/docs/workflows/streaming).

```php
namespace Queuety\Contracts;

interface StreamingStep {
    public function stream( array $state, array $existing_chunks = [] ): \Generator;
    public function on_complete( array $chunks, array $state ): array;
    public function config(): array;
}
```

| Método | Descrição |
|---|---|
| `stream( $state, $existing_chunks )` | Gerador que produz partes de texto. Cada produção aciona uma gravação imediata no banco de dados. Em caso de nova tentativa, `$existing_chunks` contém as partes persistidas anteriormente. |
| `on_complete( $chunks, $state )` | Chamado após o término do fluxo. Retorna dados para mesclar ao estado do fluxo de trabalho. |
| `config()` | Configuração opcional. Suporta `max_attempts`, `backoff`, `concurrency_group`, `concurrency_limit` e `cost_units`. |

### `ChunkStore`

Gerencia a persistência de partes para etapas de streaming. Acesse por meio de `Queuety::chunk_store()`.

| Método | Retorna | Descrição |
|---|---|---|
| `get_chunks( int $job_id )` | `string[]` | Busca todas as partes de um trabalho, ordenadas pelo índice da parte |
| `append_chunk( int $job_id, int $chunk_index, string $content, ?int $workflow_id, ?int $step_index )` | `void` | Acrescenta uma única parte |
| `clear_chunks( int $job_id )` | `void` | Exclui todas as partes de um trabalho |
| `chunk_count( int $job_id )` | `int` | Conta as partes de um trabalho |
| `get_accumulated( int $job_id )` | `string` | Concatena todas as partes em uma única string |

### `Heartbeat`

Auxiliar estático para enviar batimentos de atividade dentro de manipuladores de etapas e etapas de streaming. Consulte [Batimentos](https://queuety.inline0.dev/pt/docs/features/heartbeats).

| Método | Descrição |
|---|---|
| `Heartbeat::init( int $job_id, Connection $conn )` | Define o contexto do trabalho. Chamado automaticamente pelo worker. |
| `Heartbeat::beat( array $progress = [] )` | Envia um batimento. Atualiza `reserved_at` e, opcionalmente, armazena dados de progresso em `heartbeat_data`. |
| `Heartbeat::clear()` | Limpa o contexto do trabalho. Chamado automaticamente pelo worker. |
| `Heartbeat::current_job_id()` | Obtém o ID do trabalho atual (para testes). |

### `Contracts\Middleware`

Interface para middleware de trabalhos. O middleware envolve a execução do trabalho em um pipeline em formato de cebola.

```php
namespace Queuety\Contracts;

interface Middleware {
    public function handle( object $job, \Closure $next ): void;
}
```

## Traits

### `Dispatchable`

Fornece métodos estáticos de despacho em classes de trabalho que implementam `Contracts\Job`. Os argumentos do construtor são repassados para criar a instância do trabalho.

```php
use Queuety\Contracts\Job;
use Queuety\Dispatchable;

class SendEmailJob implements Job {
    use Dispatchable;
    // ...
}

// Dispatches a new SendEmailJob instance
SendEmailJob::dispatch( 'user@example.com', 'Subject', 'Body' );
```

| Método | Retorna | Descrição |
|---|---|---|
| `dispatch( ...$args )` | `PendingJob` | Cria uma instância e a despacha |
| `dispatch_if( bool $condition, ...$args )` | `PendingJob\|null` | Despacha somente se `$condition` for verdadeiro |
| `dispatch_unless( bool $condition, ...$args )` | `PendingJob\|null` | Despacha somente se `$condition` for falso |
| `with_chain( array $jobs )` | `ChainBuilder` | Inicia uma cadeia a partir desta classe de trabalho |

```php
// Conditional dispatch
SendEmailJob::dispatch_if( $user->wants_email, $user->email, 'Hello', 'Hi!' );
SendEmailJob::dispatch_unless( $maintenance_mode, $user->email, 'Hello', 'Hi!' );

// Chain from a job class
FetchDataJob::with_chain( [
    new ProcessDataJob(),
    new NotifyCompleteJob(),
] )->dispatch();
```

### Propriedades do trabalho

As classes de trabalho podem declarar propriedades públicas que o worker lê por reflexão para substituir o comportamento de novas tentativas e de tempo limite.

| Propriedade | Tipo | Descrição |
|---|---|---|
| `$tries` | `int` | Número máximo de tentativas antes de o trabalho ser enterrado |
| `$timeout` | `int` | Tempo máximo de execução em segundos (requer `pcntl`) |
| `$backoff` | `array` | Atrasos progressivos, em segundos, para cada tentativa |

```php
class ImportProductsJob implements Job {
    use Dispatchable;

    public int $tries = 5;
    public int $timeout = 120;
    public array $backoff = [ 10, 30, 60, 120 ];

    // ...
}
```

### Hook `failed()`

Quando um trabalho é enterrado após esgotar todas as tentativas, o worker chama um método `failed()` na instância do trabalho, se definido.

```php
public function failed( \Throwable $exception ): void {
    error_log( "Job failed: {$exception->getMessage()}" );
}
```

## Middleware integrado

Todas as classes de middleware implementam `Contracts\Middleware` e estão localizadas no namespace `Queuety\Middleware`.

| Classe | Descrição |
|---|---|
| `RateLimited( int $max, int $window )` | Impõe um limite de taxa de `$max` execuções a cada `$window` segundos |
| `Timeout( int $seconds )` | Encerra o trabalho após `$seconds` segundos (requer `pcntl`) |
| `UniqueJob( ?string $key )` | Impede execuções simultâneas por meio de um bloqueio no banco de dados |
| `WithoutOverlapping( string $key, int $release_after )` | Impede execuções sobrepostas com expiração automática do bloqueio |
| `ThrottlesExceptions( int $max_attempts, int $decay_minutes )` | Limita as exceções para evitar tempestades de trabalhos quando um serviço externo está fora do ar |

Consulte [Middleware](https://queuety.inline0.dev/pt/docs/features/middleware) para ver detalhes de uso e exemplos.

## Enums

### `Priority`

```php
enum Priority: int {
    case Low    = 0;
    case Normal = 1;
    case High   = 2;
    case Urgent = 3;
}
```

### `JobStatus`

```php
enum JobStatus: string {
    case Pending    = 'pending';
    case Processing = 'processing';
    case Completed  = 'completed';
    case Failed     = 'failed';
    case Buried     = 'buried';
}
```

### `WorkflowStatus`

```php
enum WorkflowStatus: string {
    case Running        = 'running';
    case Completed      = 'completed';
    case Failed         = 'failed';
    case Paused         = 'paused';
    case WaitingForSignal  = 'waiting_for_signal';
    case WaitingForWorkflows = 'waiting_for_workflows';
    case Cancelled      = 'cancelled';
}
```

### `StateMachineStatus`

```php
enum StateMachineStatus: string {
    case Running = 'running';
    case WaitingEvent = 'waiting_event';
    case Completed = 'completed';
    case Failed = 'failed';
    case Paused = 'paused';
    case Cancelled = 'cancelled';
}
```

### `BackoffStrategy`

```php
enum BackoffStrategy: string {
    case Fixed       = 'fixed';
    case Linear      = 'linear';
    case Exponential = 'exponential';
}
```

### `ForEachMode`

```php
enum ForEachMode: string {
    case All = 'all';
    case FirstSuccess = 'first_success';
    case Quorum = 'quorum';
}
```

### `WaitMode`

```php
enum WaitMode: string {
    case All    = 'all';
    case Any    = 'any';
    case Quorum = 'quorum';
}
```

### `LogEvent`

```php
enum LogEvent: string {
    case Started                  = 'started';
    case Completed                = 'completed';
    case Failed                   = 'failed';
    case Buried                   = 'buried';
    case Retried                  = 'retried';
    case WorkflowStarted          = 'workflow_started';
    case WorkflowCompleted        = 'workflow_completed';
    case WorkflowFailed           = 'workflow_failed';
    case WorkflowPaused           = 'workflow_paused';
    case WorkflowResumed          = 'workflow_resumed';
    case WorkflowCancelled        = 'workflow_cancelled';
    case WorkflowRewound          = 'workflow_rewound';
    case WorkflowForked           = 'workflow_forked';
    case WorkflowDeadlineExceeded = 'workflow_deadline_exceeded';
    case Debug                    = 'debug';
}
```

### `OverlapPolicy`

```php
enum OverlapPolicy: string {
    case Allow  = 'allow';
    case Skip   = 'skip';
    case Buffer = 'buffer';
}
```

Consulte [Agendamento](https://queuety.inline0.dev/pt/docs/features/scheduling) para saber como cada política funciona.

## Atributos

### `#[QueuetyHandler]`

PHP atributo 8 para registro automático. Consulte [PHP Atributos](https://queuety.inline0.dev/pt/docs/features/attributes).

```php
use Queuety\Attributes\QueuetyHandler;

#[QueuetyHandler( name: 'send_email', queue: 'emails', max_attempts: 5 )]
class SendEmailHandler implements Handler {
    // ...
}
```

## Ponte de CLI

### `Queuety::cli_command()`

Retorna o nome do comando raiz de WP-CLI publicado.

O comando raiz padrão é `queuety`. Defina `QUEUETY_CLI_COMMAND` antes que Queuety seja inicializado se o comando deve ser publicado com outro nome.

### `Queuety::cli_command_map()`

Retorna o catálogo serializável de comandos Queuety CLI para ambientes de teste que precisam entender a superfície de comandos disponibilizada sem analisar classes WP-CLI.

Cada entrada inclui:
- um ID de operação estável
- o caminho relativo de CLI
- a classe e o método do manipulador WP-CLI
- os possíveis destinos de execução
- o adaptador que normaliza os argumentos brutos CLI em um plano de execução

### `Queuety::resolve_cli_command( $path, $args, $assoc_args )`

Transforma uma invocação CLI analisada no plano de execução que o ambiente de teste deve executar.

```php
$plan = Queuety::resolve_cli_command(
    [ 'workflow', 'export' ],
    [ '42' ],
    [ 'output' => '/tmp/workflow.json' ]
);

echo $plan['callable']; // Queuety\Queuety::export_workflow_to_file
print_r( $plan['arguments'] );
```

Os planos de execução levam em conta o transporte de propósito:
- os comandos são resolvidos para funções chamáveis públicas PHP com argumentos normalizados
- o catálogo lista previamente todos os destinos de execução possíveis, enquanto `callable` e `transport` identificam a ramificação escolhida para a entrada analisada

Este é o padrão de uso de Queuety para ambientes de teste de agentes: ID de operação estável, destino público API e normalização sob responsabilidade do adaptador para preocupações exclusivas de CLI, como padrões de fila, decodificação de cargas úteis JSON, ramificações do pool de workers e manipulação de arquivos de exportação de fluxos de trabalho.