---
id: WF-PFM-LLM-008
title: Grant and revoke temporary AI capacity
trigger: Provide or revoke temporary AI capacity.
product_area: platform
module: llm
revision: 1
status: draft
design_intent: proposed
origin: >-
  Ceilings by D-3 and the optional restoration notice by D-4 (Andrew, 2026-10-18,
  services-platform:docs/proposals/llm-observability/11-decisions.md#Decision record); the controls' milestone
  PLAT-M2 is proposed.
implementation_evidence: partially-observed
inference: []
source_sha:
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
  react-console: baf6dae382d6f41dce976c7f848667ccc37e076f
implements:
  - CAP-PFM-LLM-014
moves:
  - STATE-PFM-LLM-007
  - STATE-PFM-LLM-005
crosses:
  - SVC-PFM-LLM-llm
idempotency: >-
  Grant creation has no replay key and can duplicate capacity; repeated revocation refuses the already revoked
  row.
concurrency: >-
  Organization advisory locks serialize grant peak checks; revocation locks its record. Requests already
  admitted preserve their holds.
hops:
  - 'n': 1
    actor_or_service: Rhythm HQ console
    action: Display calculated grant states and a disabled management action without revocation controls.
    anchor: 'react-console:components/console/hq/tenant-ai-usage-card.tsx:AiUsageMenu'
    seam: sync
    on_failure: There is no implemented screen mutation.
    left_inconsistent: No grant is changed by the card.
    observer: API response and security audit history for committed control changes.
    provenance: observed
    source: 'react-console:components/console/hq/tenant-ai-usage-card.tsx:OverrideList'
  - 'n': 2
    actor_or_service: LLM usage API
    action: 'Authorize grant, preview and revoke using the management route.'
    anchor: 'services-platform:modules/llm/aws/api/llm-usage.routes.ts:grantHqTenantLlmUsageOverride'
    seam: sync
    on_failure: Reject unauthorized or invalid requests.
    left_inconsistent: No accepted grant mutation occurs.
    observer: API response and security audit history for committed control changes.
    provenance: observed
    source: 'services-platform:modules/llm/aws/api/llm-usage-api-mapper.ts:mapOverrideGrantRequest'
  - 'n': 3
    actor_or_service: Grant service
    action: 'Validate grant kind, amount or operation, window, reason and ticket.'
    anchor: 'services-platform:modules/llm/services/overrides/allowance-overrides.ts:validateOverrideRequest'
    seam: sync
    on_failure: Reject invalid values before creating a record.
    left_inconsistent: No grant or audit is created.
    observer: API response and security audit history for committed control changes.
    provenance: observed
    source: 'services-platform:modules/llm/services/overrides/allowance-overrides.ts:validateOverrideRequest'
  - 'n': 4
    actor_or_service: Grant service
    action: >-
      Lock organization grants, check peak capacity and commit the grant with its audit; preview only
      projects.
    anchor: 'services-platform:modules/llm/services/overrides/allowance-overrides.ts:grantOverride'
    seam: sync
    on_failure: Reject ceiling breaches and roll back a failed create and audit together.
    left_inconsistent: Preview creates no persistent effect; successful repeated creates can still duplicate capacity.
    observer: API response and security audit history for committed control changes.
    provenance: observed
    source: 'services-platform:modules/llm/services/overrides/allowance-overrides.ts:previewOverride'
  - 'n': 5
    actor_or_service: Grant service and shared e-mail sender
    action: 'After commit, optionally notify administrators when capacity restores a stopped organization.'
    anchor: 'services-platform:modules/llm/services/notices/override-notice.ts:sendOverrideGrantedNotice'
    seam: sync
    on_failure: Log and measure notice failure without retry or rollback.
    left_inconsistent: The grant remains effective even when nobody hears about it.
    observer: API response and security audit history for committed control changes.
    provenance: observed
    source: 'services-platform:modules/llm/services/notices/override-notice.ts:sendOverrideGrantedNotice'
  - 'n': 6
    actor_or_service: Grant service (revocation)
    action: Lock and revoke an unended grant with reason and audit in the same transaction.
    anchor: 'services-platform:modules/llm/services/overrides/allowance-overrides.ts:revokeOverride'
    seam: sync
    on_failure: 'Reject ended, revoked, missing or foreign grants; roll back write failures.'
    left_inconsistent: Original grant details remain with either a complete revocation or no revocation.
    observer: API response and security audit history for committed control changes.
    provenance: observed
    source: 'services-platform:modules/llm/services/persistence/overrides.ts:revokeOverrideRow'
branches:
  - The structured hops retain the applicable alternative path and its failure boundary.
waits: []
evidence:
  - >-
    services-platform at ad3f6a6: modules/llm/aws/api/llm-usage.routes.ts, llm-usage-api-mapper.ts;
    services/overrides/allowance-overrides.ts; services/persistence/overrides.ts;
    services/notices/override-notice.ts; db/llm-allowance-overrides.table.ts; llm.settings.ts;
    tests/e2e/llm-overrides.e2e.spec.js; docs/llm.md#Overrides.
  - 'react-console at baf6dae: components/console/hq/tenant-ai-usage-card.tsx.'
controls: [TC-AVL-004, TC-AVL-005, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-005, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-IAM-001, TC-IAM-002, TC-IAM-003, TC-IAM-004, TC-IAM-005, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-MON-001, TC-MON-002, TC-MON-003, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-004, TC-PI-005, TC-PRV-001, TC-PRV-002, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-VEN-001, TC-VEN-002, TC-VEN-003]
---

# Grant and revoke temporary AI capacity

## What It Does

Staff can preview and create extra credits or an operation exemption through the service. The organization card exposes no enabled create or revoke flow.

## The Flow

```mermaid
flowchart TD
  H1["Display calculated grant states and a disabled management action without revocation controls."]
  H2["Authorize grant, preview and revoke using the management route."]
  H1 --> H2
  H3["Validate grant kind, amount or operation, window, reason and ticket."]
  H2 --> H3
  H4["Lock organization grants, check peak capacity and commit the grant with its audit; preview only projects."]
  H3 --> H4
  H5["After commit, optionally notify administrators when capacity restores a stopped organization."]
  H4 --> H5
  H6["Lock and revoke an unended grant with reason and audit in the same transaction."]
  H5 --> H6
```

Validate the window and peak allowance under the organization lock, then commit grant and audit. A requested qualifying restoration email follows commit.

## When Something Fails

Repeated creates produce additional grants. Notice failure leaves capacity intact without retry. Revocation refuses ended or previously revoked grants.

## Open Design Questions

The recorded ceiling and interim notice audience remain the existing decisions; replay safety and console wiring remain preparation gaps.