docs(traffic): define shared pool accounting contract

go
codex 3 weeks ago
parent 69f051a01a
commit 07ebfd4a64

@ -0,0 +1,138 @@
# Shared traffic-pool contract
## Scope
The traffic pool is a prepaid accounting projection. It does not replace
orders or service periods. Every purchase or renewal still creates one
independent `cloud_service_periods` row, and that period is the only source of
traffic entitlement.
A pool is identified by `(user_id, traffic_pool_group_id)`. A traffic-pool
group is a stable commercial line identity. Different groups never share
quota, even when their hosts or public bridges are technically interchangeable.
Orders and service periods freeze the group identity at purchase time.
The first release does not support moving an active service period between
traffic-pool groups. Host maintenance migration is permitted only when the
source and target remain in the same group.
## Entitlements
Each service period materializes at most one entitlement.
- A future period is `scheduled` and contributes no usable bytes.
- At `starts_at`, its complete finite quota becomes active exactly once.
- A paid upgrade may only increase the active entitlement. The positive
difference keeps the original `ends_at` and is idempotent by upgrade source.
- At `ends_at`, only that entitlement's unused bytes are forfeited. Previously
consumed bytes remain immutable history.
- Deleting an instance early does not erase its paid entitlement. Other
instances in the same pool may consume it until the original `ends_at`.
- An unlimited period is excluded from the finite pool: its instance neither
contributes infinite quota nor consumes finite entitlements.
- A maintenance migration or an in-place restore never creates another
entitlement. A backup copy receives quota only through a new paid service
period.
## Usage allocation
Only the Agent's durable cumulative public-interface RX and TX counters are
billable. VPC-interface traffic is outside this contract. PHP persists those
counters monotonically before traffic-pool settlement.
New usage is allocated across active finite entitlements in strict FEFO order:
```text
ends_at ASC, entitlement_id ASC
```
The instance that generated the traffic does not own the consumed
entitlement. Entitlement origin remains audit metadata only.
All mutations for one pool serialize under a single pool row lock. The lock
order is always:
```text
pool -> instance cursor -> entitlements -> network restrictions
```
The accounting transaction advances the instance cursor, appends immutable
ledger events, updates entitlement and pool projections, and updates desired
network restrictions atomically. It never calls an Agent while holding a
database transaction.
Repeated observations and repeated lifecycle finalization must have no new
effect. A counter regression is an attention condition; it must not refund
traffic or charge the observed total from zero.
## Sampling overage and expiry boundaries
Polling cannot stop traffic at an exact byte. If an observation exceeds the
available pool balance, the remaining entitlements are consumed, the excess is
recorded as `overage_bytes`, and the pool becomes exhausted. A later finite
entitlement first settles that debt before exposing usable bytes. Overage is
never silently discarded.
At `ends_at`, an entitlement immediately stops contributing visible or
allocatable balance. A bounded `closing` interval may settle observations
whose trusted `observed_at` is not later than `ends_at`. Closing must end after
at most two normal collection intervals; a missing host cannot keep a paid
period or pool permanently locked.
## Network policy
Traffic accounting owns only the `traffic_pool_exhausted` network restriction.
Service expiry and administrator policy have independent reasons. Public
network access is desired only when no active restriction exists.
When a pool is exhausted, all active finite instances in that user and group
receive the traffic restriction. When usable balance returns, accounting
removes only its own restriction. It must never clear `service_expired`,
`admin_hold`, or another module's restriction.
Remote network mutations use the existing durable job and operation-identity
contracts. A timeout or malformed receipt has unknown effect: retain the
original operation identifier for reconciliation and never automatically
replay it.
## Read model
User and administrator pages read a pool snapshot produced by the accounting
module. They do not sum entitlements themselves.
The primary user values are:
- currently active finite quota;
- consumption from currently active entitlements;
- usable balance;
- unsettled sampling overage;
- the next expiry time and the unused bytes that will be forfeited then;
- last trusted observation and network-restriction state.
Lifetime or calendar-month usage is a separate statistic. It must not be
divided by the currently active quota because expired entitlements legitimately
make historical usage greater than the quota still active today.
## Conservation and recovery invariants
For every entitlement:
```text
granted_bytes = consumed_bytes + remaining_bytes + forfeited_bytes
```
For accepted traffic observations:
```text
observed_delta = allocated_consumption + overage_delta
```
No projection may become negative. Immutable ledger events are the audit
source; pool, entitlement and cursor projections must be verifiable from them.
Projection mismatch fences automatic network restoration for that pool but
does not delete the ledger or issue another remote mutation.
Before enforcement, the feature may run in shadow mode. After traffic has
been shared across instances, rolling back to per-instance balances is not
safe; recovery must pause new network mutations, retain the ledger and repair
or rebuild the projection forward.
Loading…
Cancel
Save