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

# Inbound queue SLA forecast + virtual callback gate

> How Orbit's queue-entry SLA forecast steers a new inbound caller to the press-1 virtual-callback consent when the queue has already missed its own service-level target — so a caller does not accrue real hold on a breaching queue.

# Inbound queue SLA forecast + virtual callback gate

Orbit's ACD queue entry check forecasts whether the head-of-line (or a new caller's projected wait) will breach the queue's **SLA threshold** — the per-queue target the supervisor surface already shows. When a queue opts the new `slaCallbackPolicy` field into `suggest` or `block`, the engine guards entries accordingly:

* **suggest** — entry still allowed; the supervisor surface marks "press 1 for a callback" as advised for this tick.
* **block** — the entry check refuses the ZADD and routes the caller to the press-1 virtual-callback consent (position saved; the callback-in-queue dispatcher dials them on the Devotel softswitch, not an outbound Telnyx/DIDWW agent — respect the invariant).

## Fields

| `QueueConfig` field         | Default | Description                                                      |
| --------------------------- | ------- | ---------------------------------------------------------------- |
| `targetServiceLevelSeconds` | 20      | Per-queue SLA threshold in seconds ("answer within N s"). 5–300. |
| `slaCallbackPolicy`         | omitted | `'suggest'` or `'block'`. Omitted = fail-open.                   |

## Supervisor verdict

`computeSlaCallbackGate` returns `{ verdict, projectedWaitSeconds, breachOverSeconds, alreadyBreached }`:

* `verdict`: `ok`, `suggest`, or `block`.
* `projectedWaitSeconds`: position-based estimate.
* `breachOverSeconds`: the deeper of head-of-line overhang vs position math; used to surface "how much capacity callback would absorb".
* `alreadyBreached`: head-of-line already past threshold (a 0-waiting queue can still be flagged).

The supervisor read-model and the request-path entry check use the same engine so the two surfaces cannot drift.

## Entry decision flow

1. The queue controller fetches `getQueueStats` + `getQueueConfig`.
2. If `slaCallbackPolicy` is absent → the block check is skipped.
3. When `'block'` and the forecast is a breach → the controller responds `503` with `slaCallbackBlocked: true, projectedWaitSecs, slaThresholdSecs` and fires `handleOverflow(call, 'callback', ...)`. The caller hears the press-1 prompt and consents a callback whose position is preserved.
4. Queues without the field engage only the existing press-1 escape — nothing else changes.

## Dispatch safety

The blocked-entry path is the same `callback` overflow `handleOverflow` the existing `press-1` escape uses, so it lands in the normal `callback_requests` / `callback_in_queue` dispatch path. The callback dispatcher enforces:

* Emergency-dial guard (invariant #49).
* TCPA federal-window check (invariant #68) for +1 NANP.
* Devotel softswitch trunk for dialbacks (invariant #45).

## Example PATCH

```http theme={null}
PATCH /api/v1/voice/queue/queue_abc123
{
  "targetServiceLevelSeconds": 30,
  "slaCallbackPolicy": "block"
}
```

The queue will now protect every inbound call against accruing hold on an already-breaching queue and steer it to virtual callback instead.