Rhythm 2.0 Specifications

Appearance

DOM-PFM-LLM-003AI Allowance

Markdown

DOM-PFM-LLM-003

AI Allowance

Markdown
  • DocumentDraft
  • ImplementationObserved

Planning

Specified by
CON-PFM-LLM-003

Design

Owned by
SVC-PFM-LLM-llm

KindDomain objectProduct areaPlatformModuleAI Requests, Usage and the Jazz AI TeammateRevision1

Read atservices-platform ad3f6a65react-console baf6dae3

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.

Relationships

ToCardinalityOwnershipCrosses a serviceOn archive or delete
DOM-PFM-LLM-001one monthly period to many requestsRequests retain their source facts; this relationship does not transfer request ownership.no
DOM-PFM-LLM-002limits and exemptions name many operations by keyThe operation catalogue owns its definitions; related records keep references.no
DOM-PFM-LLM-004one allowance supplies the live position of one organization's usageReporting derives its values without owning the underlying records.no

Invariants

InvariantProtectsEnforced atProvenance
INV-DOM-PFM-LLM-003-01
The organization and local month uniquely identify an allowance period created when needed.
service, databaseobserved
services-platform:modules/llm/services/persistence/allowance-periods.ts:getOrCreateAllowancePeriod
INV-DOM-PFM-LLM-003-02
One conditional update reserves credits and a running slot only when capacity and concurrency predicates pass.
databaseobserved
services-platform:modules/llm/services/persistence/allowance-periods.ts:authorizeCredits
INV-DOM-PFM-LLM-003-03
Settlement or release removes the hold and running slot with values floored at zero.
service, databaseobserved
services-platform:modules/llm/services/persistence/allowance-periods.ts:settleCredits
INV-DOM-PFM-LLM-003-04
Database checks prevent negative period allowance, charges, holds and running counts.
databaseobserved
services-platform:modules/llm/db/llm-allowance-periods.table.ts:llm_allowance_periods_reserved_credits_check
INV-DOM-PFM-LLM-003-05
Admission includes unrevoked grants only within their inclusive-start, exclusive-end window.
databaseobserved
services-platform:modules/llm/services/persistence/allowance-periods.ts:authorizeCredits
INV-DOM-PFM-LLM-003-06
Grant checks require an ordered window and require an operation key only for exemptions.
databaseobserved
services-platform:modules/llm/db/llm-allowance-overrides.table.ts:llm_allowance_overrides_operation_key_check
INV-DOM-PFM-LLM-003-07
Grant creation serializes overlap checks for the organization and rejects a peak above the platform ceiling.
service, databaseobserved
services-platform:modules/llm/services/persistence/overrides.ts:lockTenantOverrides
INV-DOM-PFM-LLM-003-08
The supported grant API preserves original values and permits one revocation before expiry.
service, databaseobserved
services-platform:modules/llm/services/persistence/overrides.ts:revokeOverrideRow
INV-DOM-PFM-LLM-003-09
Changed limits require the inspected version; matching stored values return unchanged despite a stale version.
service, databaseobserved
services-platform:modules/llm/services/persistence/limits.ts:writeTenantLimits
INV-DOM-PFM-LLM-003-10
Synchronizing limits updates the current base and configuration version without altering past months, charges or holds.
serviceobserved
services-platform:modules/llm/services/persistence/allowance-periods.ts:syncAllowancePeriodToLimits
INV-DOM-PFM-LLM-003-11
Settlements create at most one crossing per month and threshold from charged credits, excluding holds.
service, databaseobserved
services-platform:modules/llm/services/metering/llm-credit-ledger.ts:evaluateCrossings
INV-DOM-PFM-LLM-003-12
Applying a signed correction retains its full amount while flooring resulting period charges at zero.
service, databaseobserved
services-platform:modules/llm/services/persistence/allowance-periods.ts:applyAllowanceAdjustment

The Markdown files under specs/ in rhythmsoftware/rhythm-v2-docs are the canonical source of truth. This reader is a generated, read-only projection of them.

Rhythm Software