--- id: STATE-PFM-LLM-005 title: Allowance position object: DOM-PFM-LLM-003 product_area: platform module: llm revision: 1 status: draft design_intent: proposed implementation_evidence: observed source_sha: services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 states: - name: within meaning: Enabled work is below eighty percent of current effective allowance. - name: warned meaning: Enabled work has committed at least eighty percent but less than its effective allowance. - name: hard_stopped meaning: 'Committed usage reaches effective capacity, including a zero allowance.' - name: disabled meaning: The displayed organization or AI availability takes precedence over allowance figures. transitions: - from: within to: warned trigger: Commitments increase or effective capacity decreases into warning range. guard: Live committed usage reaches eighty percent while remaining below full capacity. side_effects: - Recompute display status; a notice still requires a charged-usage crossing. who: 'Any change to the figures (runtime, Rhythm staff, the passage of a grant''s end)' provenance: observed source: 'services-platform:modules/llm/services/usage-reports/usage-status.ts:deriveUsageStatus' - from: warned to: hard_stopped trigger: Committed usage reaches full effective capacity. guard: Committed credits are at least the effective allowance. side_effects: - Subsequent reservations that do not fit are refused while running work may finish. who: Any change to the figures provenance: observed source: 'services-platform:modules/llm/services/usage-reports/usage-status.ts:deriveUsageStatus' - from: within to: hard_stopped trigger: A large movement skips directly from below warning to full usage. guard: Committed usage is at least effective capacity. side_effects: - Display stopped; threshold notices depend on charges rather than holds. who: Any change to the figures provenance: inferred source: 'services-platform:modules/llm/services/usage-reports/usage-status.ts:deriveUsageStatus' - from: hard_stopped to: within trigger: 'Capacity rises, commitments fall or the month changes.' guard: AI is available and live utilisation falls below eighty percent. side_effects: - An optional qualifying restoration notice can accompany a newly granted capacity record. who: 'Rhythm staff, the runtime, or the calendar' provenance: observed source: 'services-platform:modules/llm/services/overrides/allowance-overrides.ts:grantOverride' - from: hard_stopped to: warned trigger: Capacity returns without removing the warning. guard: AI is available and utilisation lies from eighty to below one hundred percent. side_effects: - Only the calculated position changes. who: 'Rhythm staff, the runtime, or the calendar' provenance: observed source: 'services-platform:modules/llm/services/usage-reports/usage-status.ts:deriveUsageStatus' - from: warned to: within trigger: Capacity increases or commitments decrease below warning. guard: AI is available and utilisation is below eighty percent. side_effects: - Recompute within status without altering recorded crossings. who: 'Rhythm staff, the runtime, or the calendar' provenance: observed source: 'services-platform:modules/llm/services/usage-reports/usage-status.ts:deriveUsageStatus' - from: within to: disabled trigger: The AI switch is disabled or organization availability changes. guard: A live availability read reports disabled. side_effects: - >- Refuse new work when the AI switch is off; retain admitted work and apply organization availability through its separate access boundary. who: Rhythm Administrator (limits change) or the organization lifecycle provenance: observed source: 'services-platform:modules/llm/services/limits/tenant-limits.ts:checkOperationAccess' - from: disabled to: within trigger: AI and organization availability return. guard: 'Availability permits work; current usage decides within, warned or stopped.' side_effects: - A limits write that enables AI records widening in its audit event. who: Rhythm Administrator provenance: observed source: 'services-platform:modules/llm/services/limits/tenant-limits.ts:upsertTenantLimits' invalid: - from: disabled to: hard_stopped why: Disabled display takes precedence while unavailability remains in effect. - from: hard_stopped to: within why: >- Sending a notice alone cannot restore capacity; this same state pair is valid when allowance figures change. concurrency: >- The display calculates from separately read capacity and access data. Concurrent changes can alter results at the same supplied clock instant. When period data is missing, crossings can provide fallback classification. Admission uses the reservation predicate, not display status. invariants: - INV-DOM-PFM-LLM-003-02 - INV-DOM-PFM-LLM-003-05 evidence: - >- services-platform at ad3f6a6: modules/llm/services/usage-reports/usage-status.ts, tenant-positions.ts; services/usage/organization-usage.ts (organizationStatusOf); services/limits/tenant-limits.ts; services/overrides/allowance-overrides.ts. --- # Allowance position ## The Lifecycle ```mermaid stateDiagram-v2 within --> warned warned --> hard_stopped within --> hard_stopped hard_stopped --> within hard_stopped --> warned warned --> within within --> disabled disabled --> within ``` ## Transitions Explained Allowance position is recalculated rather than persisted. Holds count toward commitments, so starting and settling work can move the display in either direction. Customer summaries present stopped and disabled through a limited status. The listed arrows illustrate changes to derived inputs rather than commands in a stored state machine. ## What Cannot Happen Notification attempts do not alter capacity. Disabled availability takes display precedence, but a subsequently enabled organization can immediately be within, warned or stopped according to current figures. ## Concurrency and Timing Display status counts charged and held credits; notices inspect charges; admission needs room for a complete estimate. These different predicates explain refusal before the displayed allowance reaches full utilisation.