---
title: "Reserve, settle, and release"
description: "Follow the concurrency-safe quota lifecycle before provider dispatch and through every streaming terminal state."
---

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

# Reserve, settle, and release

## Outcome

你可以判断请求在何时占用、扣除或归还 Units，并验证普通响应、Streaming、失败和断开最终只产生一个结算结果。

```text
                        ┌─ actual usage ─────→ SETTLED
request → ACTIVE reserve├─ no delivered usage → RELEASED
                        └─ recovery timeout ──→ EXPIRED
```

三个终态都不可返回 ACTIVE，也不能互相切换。

## Reserve before the Provider

Gateway 先估算 Input，并用 Period Snapshot 的安全输出上限计算 `reserveUnits`。PostgreSQL 事务锁定当前 QuotaPeriod，校验 Available Units，创建 ACTIVE QuotaReservation，再增加 `reservedUnits`。

只有事务提交后，Gateway 才获得可调度的 ProviderConnection。额度不足、Access 无效或数据库不可用时，Provider 不会被调用。

## Settle with actual usage

响应或 Stream 提供可证明 Usage 后，Settlement 使用 Reserve 时保存的倍率快照计算 Actual Units：

```text
reservedUnits -= reservation.heldUnits
consumedUnits += actualUnits
reservation.status = SETTLED
append immutable UsageEvent
```

Cached Token 在 Reserve 前通常未知；Settle 按真实 Cached Usage 重新计算并释放差额。

## Release when nothing was delivered

请求在 Provider 前失败，或 Provider 完全失败且没有向用户交付可计量结果时，Release 归还全部 Held Units，并把 Reservation 标为 `RELEASED`。Provider Attempt 的错误或成本观察事实仍可保留。

## Streaming and cancellation

- 正常 Stream 结束：按末尾 Usage 或可证明计量结果 Settle。
- 客户端断开：取消向上游传播，按已交付或 Provider 返回的可证明 Usage Settle，其余释放。
- Provider 超时或错误：根据是否有有效交付选择 Settle 或 Release。
- 进程中断：Worker 查找过期 ACTIVE Reservation，并按幂等规则恢复到确定终态。

## Idempotency is mandatory

Reserve、Settle、Release、Recovery 和 UsageEvent 都使用稳定 Idempotency Key。重复完成事件不能重复扣量，重复 Release 不能增加 Available Units，迟到事件不能覆盖已经确定的终态。

## Check your work

- 每个 Invocation 最多有一条 ACTIVE Reservation，并最终进入一个终态。
- `reservedUnits + consumedUnits` 从不超过 `grantedUnits`。
- 被 Quota 拒绝的请求没有 Provider Attempt。
- Request ID 可以关联 Invocation、Reservation、UsageEvent 和 Audit。

## Next steps

- [Quota strategies](/docs/control-plans-and-quota/quota-strategies)
- [Quota periods](/docs/control-plans-and-quota/quota-periods)

Source: https://nexus.microvoid.io/docs/control-plans-and-quota/reserve-settle-release/index.mdx