--- id: DOM-PFM-LLM-003 title: AI Allowance realises: CON-PFM-LLM-003 product_area: platform module: llm revision: 1 status: draft design_intent: proposed origin: >- Ceilings, notice recipients, throttling and money display follow Andrew's decisions D-3, D-4, D-6 and D-7 (services-platform:docs/proposals/llm-observability/11-decisions.md#Decision record); the ledger shape is the foundation design and the PLAT-M1 plan, which awaits approval, so the object as a whole stays proposed. implementation_evidence: observed source_sha: services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f owned_by: SVC-PFM-LLM-llm readable_by: [] lifecycle: STATE-PFM-LLM-005 custom_fields: none identity: >- The organization and local month identify an allowance period. One optional versioned limits row configures the organization; generated identifiers identify grants and corrections, and month plus threshold uniquely identifies a crossing. attributes: - name: monthly period kind: collection required: true computed: false notes: 'Retains base allowance, charged amounts, held credits, running count and configuration and row versions.' - name: limits kind: collection required: false computed: false notes: >- Optional configuration selects AI access, allowance, disabled operations, concurrency and staff notes; absence uses defaults. - name: capacity grant kind: collection required: false computed: false notes: >- Retains extra capacity or an operation exemption, its window, reason, ticket and grant and revocation attribution. - name: grant state kind: computed required: true computed: true notes: 'Computes scheduled, active, expired or revoked from time and revocation.' - name: correction kind: collection required: false computed: false notes: 'Retains a nonzero signed credit adjustment, optional monetary adjustment, request reference and reason.' - name: threshold crossing kind: collection required: false computed: false notes: 'Preserves threshold figures and notice claims, completion time and recipient count.' - name: effective allowance kind: computed required: true computed: true notes: Adds currently active credit grants to the base under the ten-million-credit ceiling. - name: committed and remaining credits kind: computed required: true computed: true notes: Committed credits include charges and holds; displayed remaining capacity cannot be negative. - name: position status kind: computed required: true computed: true notes: Computes allowance position from live capacity and access switches. relationships: - to: DOM-PFM-LLM-001 cardinality: one monthly period to many requests ownership: Requests retain their source facts; this relationship does not transfer request ownership. cross_service: false - to: DOM-PFM-LLM-002 cardinality: limits and exemptions name many operations by key ownership: The operation catalogue owns its definitions; related records keep references. cross_service: false - to: DOM-PFM-LLM-004 cardinality: one allowance supplies the live position of one organization's usage ownership: Reporting derives its values without owning the underlying records. cross_service: false invariants: - id: INV-DOM-PFM-LLM-003-01 statement: The organization and local month uniquely identify an allowance period created when needed. enforced_at: - service - database provenance: observed source: 'services-platform:modules/llm/services/persistence/allowance-periods.ts:getOrCreateAllowancePeriod' - id: INV-DOM-PFM-LLM-003-02 statement: >- One conditional update reserves credits and a running slot only when capacity and concurrency predicates pass. enforced_at: - database provenance: observed source: 'services-platform:modules/llm/services/persistence/allowance-periods.ts:authorizeCredits' - id: INV-DOM-PFM-LLM-003-03 statement: Settlement or release removes the hold and running slot with values floored at zero. enforced_at: - service - database provenance: observed source: 'services-platform:modules/llm/services/persistence/allowance-periods.ts:settleCredits' - id: INV-DOM-PFM-LLM-003-04 statement: 'Database checks prevent negative period allowance, charges, holds and running counts.' enforced_at: - database provenance: observed source: >- services-platform:modules/llm/db/llm-allowance-periods.table.ts:llm_allowance_periods_reserved_credits_check - id: INV-DOM-PFM-LLM-003-05 statement: 'Admission includes unrevoked grants only within their inclusive-start, exclusive-end window.' enforced_at: - database provenance: observed source: 'services-platform:modules/llm/services/persistence/allowance-periods.ts:authorizeCredits' - id: INV-DOM-PFM-LLM-003-06 statement: Grant checks require an ordered window and require an operation key only for exemptions. enforced_at: - database provenance: observed source: >- services-platform:modules/llm/db/llm-allowance-overrides.table.ts:llm_allowance_overrides_operation_key_check - id: INV-DOM-PFM-LLM-003-07 statement: >- Grant creation serializes overlap checks for the organization and rejects a peak above the platform ceiling. enforced_at: - service - database provenance: observed source: 'services-platform:modules/llm/services/persistence/overrides.ts:lockTenantOverrides' - id: INV-DOM-PFM-LLM-003-08 statement: The supported grant API preserves original values and permits one revocation before expiry. enforced_at: - service - database provenance: observed source: 'services-platform:modules/llm/services/persistence/overrides.ts:revokeOverrideRow' - id: INV-DOM-PFM-LLM-003-09 statement: >- Changed limits require the inspected version; matching stored values return unchanged despite a stale version. enforced_at: - service - database provenance: observed source: 'services-platform:modules/llm/services/persistence/limits.ts:writeTenantLimits' - id: INV-DOM-PFM-LLM-003-10 statement: >- Synchronizing limits updates the current base and configuration version without altering past months, charges or holds. enforced_at: - service provenance: observed source: 'services-platform:modules/llm/services/persistence/allowance-periods.ts:syncAllowancePeriodToLimits' - id: INV-DOM-PFM-LLM-003-11 statement: 'Settlements create at most one crossing per month and threshold from charged credits, excluding holds.' enforced_at: - service - database provenance: observed source: 'services-platform:modules/llm/services/metering/llm-credit-ledger.ts:evaluateCrossings' - id: INV-DOM-PFM-LLM-003-12 statement: Applying a signed correction retains its full amount while flooring resulting period charges at zero. enforced_at: - service - database provenance: observed source: 'services-platform:modules/llm/services/persistence/allowance-periods.ts:applyAllowanceAdjustment' physical: - platform.llm_allowance_periods - platform.llm_tenant_limits - platform.llm_allowance_overrides - platform.llm_allowance_adjustments - platform.llm_usage_threshold_crossings evidence: - >- services-platform at ad3f6a6: modules/llm/llm.settings.ts; db/llm-allowance-periods.table.ts, llm-tenant-limits.table.ts, llm-allowance-overrides.table.ts, llm-allowance-adjustments.table.ts, llm-usage-threshold-crossings.table.ts; services/persistence/allowance-periods.ts, limits.ts, overrides.ts; services/metering/llm-credit-ledger.ts; services/limits/tenant-limits.ts; services/overrides/allowance-overrides.ts; services/adjustments/adjust-allowance.ts; db/row-level-security.ts (exemptions); docs/proposals/llm-observability/11-decisions.md; docs/llm.md (Money, Limits, Overrides, Adjustments, Notices). --- # AI Allowance ## What It Models An organization’s AI allowance combines monthly accounting with staff-controlled limits and temporary capacity. Requests hold credits during execution and replace those holds with charges. Corrections and threshold notices retain separate records so staff can explain subsequent changes. ## Identity and Attributes The organization and local month identify a period. Configured limits have one versioned row per organization; absence selects the defaults. Grants and corrections have generated identifiers. A crossing is unique for its month and threshold and retains the figures used to decide it. Grant state and remaining capacity are calculated when read. ## Relationships Requests reserve and settle against a period. Limits and exemptions refer to catalogue operations. Usage reads allowance data to present current status. Security retains the audit events and resolves Administrator role holders for notices. ## Invariants Admission checks capacity and the running-request cap in one conditional update. Settlements floor remaining holds and running counts at zero. Grant validation checks window length, kind and overlapping capacity under the platform ceiling. Changed limits require the inspected version, while identical existing values return unchanged. Only charged usage creates threshold crossings. ## How It Is Stored and Shared The LLM service owns periods, configuration, grants, corrections and crossings. Period accounting follows organization row policy. Limits and grants use explicit organization predicates under documented row-policy exemptions. Customer summaries expose credits, percentages and reset dates; staff views also expose control and monetary details. ## Open Design Questions Admission may refuse an estimate before usage reaches the dashboard’s exhaustion threshold. Corrections and limit reductions do not trigger notices. Repeated grants or corrections create additional records, and refunds against a missing current period bypass the existing-balance check. The interim Administrator audience still needs its planned responsibility-based replacement.