> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Durable Execution Worker — API Reference

> Version: 1.0.0 Last Updated: 2026-03-18 Status: Active Module: FW

**Version:** 1.0.0\
**Last Updated:** 2026-03-18\
**Status:** Active\
**Module:** FW

***

## Edge Function: `workflow-executor-worker`

**Trigger:** pg\_cron (every minute)\
**Auth:** Service role (via `util.invoke_edge_function`)

### Response Contract

```json theme={null}
{
  "success": true,
  "correlationId": "uuid",
  "results": {
    "<organization_id>": {
      "messagesProcessed": 5,
      "succeeded": 4,
      "failed": 1,
      "dlqRouted": 0,
      "errors": ["exec-id-123: Rule not found"]
    }
  }
}
```

### Error Response

```json theme={null}
{
  "error": "Internal server error",
  "category": "RUNTIME",
  "correlationId": "uuid",
  "status": 500
}
```

***

## RPC: `fw_enqueue_form_submission_automation`

**Purpose:** User-callable enqueue path for form-submission automation (Path A fallback).

### Signature

```sql theme={null}
fw_enqueue_form_submission_automation(
  p_form_id UUID,
  p_submission_id UUID,
  p_organization_id UUID
) RETURNS UUID
```

### Parameters

| Parameter           | Type | Description                                           |
| ------------------- | ---- | ----------------------------------------------------- |
| `p_form_id`         | UUID | Form definition ID                                    |
| `p_submission_id`   | UUID | Form submission record ID                             |
| `p_organization_id` | UUID | Organization ID (validated via `fw_has_org_access()`) |

### Returns

UUID of the created `fw_workflow_executions` record, or NULL if no matching rules found.

***

## RPC: `fw_claim_queued_executions`

**Purpose:** Fallback claim path when pgmq is unavailable. Uses `FOR UPDATE SKIP LOCKED`.

### Signature

```sql theme={null}
fw_claim_queued_executions(
  p_batch_size INTEGER,
  p_org_id UUID
) RETURNS SETOF fw_workflow_executions
```

### Parameters

| Parameter      | Type    | Description                 |
| -------------- | ------- | --------------------------- |
| `p_batch_size` | INTEGER | Max records to claim (1–50) |
| `p_org_id`     | UUID    | Organization ID filter      |

### Behavior

1. Selects `fw_workflow_executions` with `status IN ('queued', 'retry_pending')` and `next_retry_at <= now()`
2. Locks rows with `FOR UPDATE SKIP LOCKED`
3. Updates status to `running`
4. Returns claimed records

***

## Queue Message Schema

### `workflow_execution_queue` Message

```json theme={null}
{
  "execution_id": "uuid",
  "rule_id": "uuid",
  "trigger_type": "form_submitted | event | manual",
  "organization_id": "uuid",
  "attempt": 1,
  "trigger_data": {
    "trigger_type": "form_submitted",
    "submission_id": "uuid",
    "form_id": "uuid",
    "organization_id": "uuid",
    "submission_data": {}
  }
}
```

### `workflow_dlq` Message

```json theme={null}
{
  "execution_id": "uuid",
  "rule_id": "uuid",
  "trigger_type": "form_submitted",
  "organization_id": "uuid",
  "attempt": 5,
  "error": "Rule not found: missing",
  "failed_at": "2026-03-18T12:00:00Z",
  "total_attempts": 5
}
```

***

## Semaphore Columns (`fw_module_settings`)

| Column                   | Type        | Description                                 |
| ------------------------ | ----------- | ------------------------------------------- |
| `worker_running`         | BOOLEAN     | Per-org lock; `true` while worker processes |
| `worker_last_run_at`     | TIMESTAMPTZ | Last successful semaphore acquisition       |
| `worker_last_batch_size` | INTEGER     | Messages processed in last run              |

***

## Related Documentation

* [FW-46 Admin Guide](durable-execution-worker-admin-guide.md)
* [FW-46 Runbook](durable-execution-worker-runbook.md)