> ## 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.

# Workflow Rate Limiting & Throttling — Integration

> Feature ID: FW-53 Status: ✅ Implemented (2026-03-23) Spec Reference: FW-53-workflow-rate-limiting-throttling.md Last Updated: 2026-03-23

**Feature ID:** FW-53\
**Status:** ✅ Implemented (2026-03-23)\
**Spec Reference:** [FW-53-workflow-rate-limiting-throttling.md](../../../specs/fw/archive/FW-53-workflow-rate-limiting-throttling.md)\
**Last Updated:** 2026-03-23

***

## Overview

FW-53 adds org- and workflow-scoped execution rate limits, event debounce, cascade-depth protection, and operational counters. Enforcement runs **inside the FW-46 durable execution worker** at dequeue/start boundaries so excess work remains queued with backpressure instead of being dropped.

***

## Integration Points (from Spec)

| Dependency    | Type                | Purpose                                                       |
| ------------- | ------------------- | ------------------------------------------------------------- |
| FW-46         | Intra-core / Worker | Evaluate limits before start; defer messages; update counters |
| FW-47         | Intra-core          | DLQ classification `cascade_detected`                         |
| FW-16 Phase 2 | Intra-core          | `correlation_id` / parent chain for cascade depth             |
| FW-03         | Intra-core          | Trigger and automation context for debounce keys              |
| PF-10         | Platform            | Warning (80%) and critical (limit hit) notifications          |
| PF-04         | Platform            | Audit trail for configuration changes                         |
| PF-43         | Platform            | Advisory quota headroom when editing limits                   |
| PF-42         | Platform            | Conceptual alignment with platform rate-limit patterns        |

***

## Worker Contract (FW-46 Extension)

**Code anchor:** `supabase/functions/workflow-executor-worker/index.ts` — async function `processMessage` (queue payload verified against `fw_workflow_executions.organization_id`; status set to `running` immediately after rule/execution fetch today — FW-53 inserts evaluation **before** that update).

1. **After** claiming a queue message, **before** marking execution `running`, call internal evaluation (SQL function or shared module):
   * Inputs: `organization_id`, `workflow_definition_id`, optional `automation_rule_id`, optional parent/correlation metadata.
   * Outputs: `{ allowed: boolean, defer_seconds?: number, reason?: string }`.
2. If not allowed: set `rate_limit_hold_until` on execution (if column present), nack/defer message with `defer_seconds` (with jitter), **do not** increment concurrent running count.
3. If allowed: increment counters atomically (transaction) with execution start; decrement on terminal completion paths (existing FW-46 completion hooks).

***

## RPC / SQL Functions (Illustrative Names)

| Name                                                | Caller                | Notes                                                                               |
| --------------------------------------------------- | --------------------- | ----------------------------------------------------------------------------------- |
| `fw_evaluate_execution_rate_limits(...)`            | Worker (service role) | Read config (cached), read/write counters; SECURITY DEFINER if invoked as non-owner |
| `fw_get_execution_rate_snapshot(p_organization_id)` | Dashboard (optional)  | Read-only aggregates; must respect tenant                                           |

Exact signatures are defined at implementation time; must not expose PHI.

***

## Event Contracts

No new cross-core outbound events in MVP. Optional future: `fw.rate_limit.threshold_exceeded` for external automation (deferred).

***

## PF-43 (Advisory)

FW settings UI SHOULD call existing quota check with `p_resource_type = 'workflow_executions'` (see `src/platform/quota/constants.ts`, `useResourceQuota` hook) so admins see PF-43 **remaining / reset\_at** alongside FW-53 per-minute and concurrency caps. Enforcement remains separate: PF-43 quotas are global per resource type; FW-53 is fine-grained workflow throttling.

***

## Security and Tenant Isolation

* `fw_rate_limit_configs`: RLS with `fw_has_org_access`; app enforces `fw.rate_limits.manage` for mutations.
* `fw_execution_rate_counters`: SELECT for org members; writes from worker/service role or SECURITY DEFINER RPCs only.
* Queue payloads remain identifier-only per FW-46.

***

## Related Docs

* [FW-53 Spec](../../../specs/fw/archive/FW-53-workflow-rate-limiting-throttling.md)
* [FW-46 Integration](./durable-execution-worker-integration.md)
* [FW-47 Integration](./dead-letter-queue-integration.md)
* [PF-42 Integration](./rate-limiting-throttling-integration.md)
* [CROSS\_CORE\_INTEGRATIONS.md](./CROSS_CORE_INTEGRATIONS.md)