---
id: STATE-PFM-LLM-007
title: Capacity grant lifecycle
object: DOM-PFM-LLM-003
product_area: platform
module: llm
revision: 1
status: draft
design_intent: proposed
origin: >-
  Ceilings by D-3 (Andrew, 2026-10-18) are confirmed; the revoke-never-edit, half-open window and read-time
  state shape is reported as settled by inspection (not asked) in the same record, following the licence
  override precedent (services-platform:docs/proposals/llm-observability/11-decisions.md#11.1 Settled by
  inspection (reported)). The milestone that owns the controls (PLAT-M2) is proposed, so the screen side is
  not confirmed by this record.
implementation_evidence: observed
source_sha:
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
states:
  - name: absent
    meaning: No capacity record exists.
  - name: scheduled
    meaning: An unrevoked grant starts later than the reading instant.
  - name: active
    meaning: The reading instant falls inside an unrevoked grant window.
  - name: expired
    meaning: The grant has ended and no longer contributes capacity.
  - name: revoked
    meaning: Revocation is recorded while preserving the original grant.
transitions:
  - from: absent
    to: active
    trigger: A manager creates capacity starting immediately.
    guard: >-
      Kind, value, declared operation, reason, future end, ninety-two-day duration and peak allowance pass
      validation.
    side_effects:
      - >-
        Commit grant and widening audit under the organization lock; optionally send a qualifying restoration
        notice afterward.
    who: Rhythm Administrator (hq.llm-usage.manage)
    provenance: observed
    source: 'services-platform:modules/llm/services/overrides/allowance-overrides.ts:grantOverride'
  - from: absent
    to: scheduled
    trigger: A manager creates capacity with a future start.
    guard: The same grant validation and peak checks pass.
    side_effects:
      - Commit grant and audit without scheduling an activation job.
    who: Rhythm Administrator (hq.llm-usage.manage)
    provenance: observed
    source: 'services-platform:modules/llm/services/overrides/allowance-overrides.ts:grantOverride'
  - from: scheduled
    to: active
    trigger: Time reaches the grant’s start.
    guard: The grant is unrevoked and its half-open window includes the reading instant.
    side_effects:
      - Later admission includes it without a state write.
    who: Time
    provenance: observed
    source: 'services-platform:modules/llm/services/persistence/allowance-periods.ts:authorizeCredits'
  - from: active
    to: expired
    trigger: Time reaches the grant’s end.
    guard: The end boundary is exclusive.
    side_effects:
      - Later admission excludes it without a state write or expiry notice.
    who: Time
    provenance: observed
    source: 'services-platform:modules/llm/services/persistence/allowance-periods.ts:authorizeCredits'
  - from: active
    to: revoked
    trigger: A manager revokes currently active capacity.
    guard: 'The grant belongs to the organization, is unrevoked and has not ended.'
    side_effects:
      - 'Commit revoker, time, reason and non-widening audit; existing holds remain.'
    who: Rhythm Administrator (hq.llm-usage.manage)
    provenance: observed
    source: 'services-platform:modules/llm/services/overrides/allowance-overrides.ts:revokeOverride'
  - from: scheduled
    to: revoked
    trigger: A manager revokes scheduled capacity.
    guard: The grant is unrevoked and has not ended.
    side_effects:
      - Retain original details with revocation and audit so the grant never becomes effective.
    who: Rhythm Administrator (hq.llm-usage.manage)
    provenance: observed
    source: 'services-platform:modules/llm/services/overrides/allowance-overrides.ts:revokeOverride'
invalid:
  - from: expired
    to: revoked
    why: The service rejects revocation after the grant ends.
  - from: revoked
    to: revoked
    why: The service rejects a second revocation.
  - from: active
    to: active
    why: There is no supported grant-edit operation; corrections use revocation and another grant.
  - from: revoked
    to: active
    why: Revocation has no reversal operation.
concurrency: >-
  An organization advisory lock serializes grant overlap checks. Revocation locks its row and updates only an
  unrevoked record. Repeated create requests can still produce multiple grants; read-time state uses each
  grant’s window and revocation.
invariants:
  - INV-DOM-PFM-LLM-003-05
  - INV-DOM-PFM-LLM-003-06
  - INV-DOM-PFM-LLM-003-07
  - INV-DOM-PFM-LLM-003-08
evidence:
  - >-
    services-platform at ad3f6a6: modules/llm/services/overrides/allowance-overrides.ts;
    services/persistence/overrides.ts; services/persistence/allowance-periods.ts:authorizeCredits;
    db/llm-allowance-overrides.table.ts; llm.settings.ts; services/notices/override-notice.ts;
    docs/llm.md#Overrides.
---

# Capacity grant lifecycle

## The Lifecycle

```mermaid
stateDiagram-v2
  absent --> active
  absent --> scheduled
  scheduled --> active
  active --> expired
  active --> revoked
  scheduled --> revoked
```

## Transitions Explained

Temporary capacity adds credits or exempts a declared operation from its operation switch. Its state is calculated from timestamps and revocation. Default windows end at the organization’s next month boundary. An exemption does not enable organization-wide AI when that switch is off.

## What Cannot Happen

Supported APIs do not edit or delete grants and reject repeated or late revocation. A new grant is required to restore revoked capacity. The state labels describe calculated eligibility rather than scheduled writes.

## Concurrency and Timing

Peak validation checks the new start and relevant overlapping starts inside its window. Admission evaluates active capacity directly. End or revocation preserves the holds of work already admitted.