Rhythm 2.0 Specifications

Appearance

CAP-PFM-LLM-007Admit AI work against the organization’s monthly allowance

Markdown

CAP-PFM-LLM-007

Admit AI work against the organization’s monthly allowance

Markdown
  • DocumentDraft
  • Product intentProposed
  • ImplementationObserved

Planning

Feature
FEAT-PFM-LLM-03
Exercised by
FAS-PFM-LLM-03-01, FAS-PFM-LLM-03-02, FAS-PFM-LLM-03-03, FAS-PFM-LLM-03-04, FAS-PFM-LLM-03-05
Key concepts
CON-PFM-LLM-003, CON-PFM-LLM-001
Actors
ACT-PFM-032, ACT-PFM-012
Journeys
JNY-PFM-LLM-001, JNY-PFM-LLM-003
Depends on
CAP-PFM-LLM-005
Related
CAP-PFM-LLM-001, CAP-PFM-LLM-008, CAP-PFM-LLM-012, CAP-PFM-LLM-013, CAP-PFM-LLM-014, CAP-PFM-LLM-015
Open questions
OQ-PFM-LLM-001
Proved by
ATS-PFM-LLM-007

Implementation

Executable suites
TST-PFM-LLM-005, TST-PFM-LLM-018, TST-PFM-LLM-019, TST-PFM-LLM-020, TST-PFM-LLM-025, TST-PFM-LLM-030, TST-PFM-LLM-031, TST-PFM-LLM-046, TST-PFM-LLM-062, TST-PFM-LLM-078

KindCapabilityProduct areaPlatformModuleAI Requests, Usage and the Jazz AI TeammateRevision1

Read atservices-platform ad3f6a65

Admit AI work against the organization’s monthly allowance ​

Purpose ​

Control new AI spending using one allowance shared across the customer’s workspace.

How It Works ​

Before a model conversation begins, Platform calculates the credits it needs to hold. The ledger evaluates the request against the organization’s current monthly period. It combines the base allowance with temporary capacity that is active at that instant. The same admission decision checks how many requests are already running. A refused request remains available for explanation but spends no model credit. When admitted work finishes, settlement replaces the hold with its charge. Changed limits affect subsequent admission while preserving existing requests. The product should reconcile admission refusals with dashboard status and notice timing before treating them as the same paused state.

Relationships ​

  • Publish AI operation definitions and historical prices supplies the prerequisite behavior for this outcome.

The Formal Contract

The narrative above explains; the sections below are authoritative — the rules, scenarios and tests this document binds.

Outcomes
Admission rejects requests whose reservation does not fit.A concurrency cap restricts simultaneous admitted requests.Dated grants affect capacity only while active.
Surfaces
apijob
Preconditions
Organization and operation switches permit admission.
Postconditions
Admission records either a reservation or its refusal figures.
Constraints
The meaning of an exhausted allowance needs a product decision when some credits remain but a reservation cannot fit.
Intent sources
services-platform:docs/proposals/llm-observability/11-decisions.md#D-3services-platform:docs/proposals/llm-observability/11-decisions.md#D-6services-platform:docs/milestones/PLAT-M1-ai-usage-metered-and-visible.md#D-3 (proposal)services-platform:docs/milestones/PLAT-M1-ai-usage-metered-and-visible.md#D-6 (proposal)

Controls

30 controls apply, from the corpus control catalogue.

TC-AVL-004 TC-AZ-001 TC-AZ-002 TC-AZ-003 TC-AZ-004 TC-AZ-006 TC-CRY-001 TC-CRY-002 TC-CRY-003 TC-CRY-004 TC-DAT-001 TC-DAT-002 TC-DAT-003 TC-LOG-001 TC-LOG-004 TC-LOG-005 TC-MON-001 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

Business Rules

11 rules, 10 to be proved before approval. A rule's product intent is derived from its origin: 0 confirmed by a product decision, the rest inheriting this capability's proposed.

IdRuleKindEnforced atProvenance
01must prove
Proposed
The organization receives one allowance period per local calendar month, created on demand with its configured allowance or the default 100,000 credits.
✓ An organization in Eastern time starts a new period at midnight on the first in its own zone.✗ Nothing has to run at month end for the allowance to start over.
proved by ATS-PFM-LLM-007-01, ATS-PFM-LLM-007-21, TST-PFM-LLM-030, TST-PFM-LLM-062
calculationservice, databaseobserved
services-platform:modules/llm/services/persistence/allowance-periods.ts
02must prove
Proposed
Admission atomically holds the estimate only if charged credits, existing holds and the new hold fit within active allowance capacity, capped at ten million credits; racing requests cannot over-reserve that capacity.
proved by ATS-PFM-LLM-005-10, ATS-PFM-LLM-007-02, ATS-PFM-LLM-007-15, ATS-PFM-LLM-007-20, TST-PFM-LLM-019, TST-PFM-LLM-025, TST-PFM-LLM-030, TST-PFM-LLM-031
calculationservice, databaseobserved
services-platform:modules/llm/services/persistence/allowance-periods.ts
03must prove
Proposed
An unaffordable request creates an allowance-refusal record with its needed and remaining credits, but sends nothing to the model and reserves and charges nothing.
proved by ATS-PFM-LLM-001-16, ATS-PFM-LLM-007-03, TST-PFM-LLM-020
policyserviceobserved
services-platform:modules/llm/services/execution/run-operation.ts
04must prove
Proposed
The concurrency default is eight requests unless organization limits specify another cap; an excess request gets a two-second retry hint, settlement or release returns its slot, and no daily cap applies.
proved by ATS-PFM-LLM-007-04, TST-PFM-LLM-019
policyservice, databasetest
services-platform:modules/llm/tests/integration/lifecycle/llm-ledger-concurrency.integration.spec.js#admits a ninth only once a call has settled, which gives its place back
05must prove
Proposed
When allowance and concurrency would both reject admission, the refusal reports the allowance.
proved by ATS-PFM-LLM-007-04, TST-PFM-LLM-019
policyservicetest
services-platform:modules/llm/tests/integration/lifecycle/llm-ledger-concurrency.integration.spec.js#says allowance_exceeded when both refuse, because that is the one that lasts
06must prove
Proposed
Capacity grants add together and apply from their start inclusive until their end exclusive or revocation, evaluated directly at request time without an activation or expiry job.
proved by ATS-PFM-LLM-007-05, ATS-PFM-LLM-007-17, TST-PFM-LLM-019
calculationservice, databaseobserved
services-platform:modules/llm/services/persistence/allowance-periods.ts
07must prove
Proposed
Already admitted work is charged its measured usage even if the period exceeds its allowance.
proved by ATS-PFM-LLM-007-06, TST-PFM-LLM-005
calculationserviceobserved
services-platform:modules/llm/services/execution/run-operation.ts
08must prove
Proposed
Lower limits preserve running requests and their holds; later admission fails while charged and held credits exceed the reduced allowance, and settlement cannot drive holds below zero.
proved by ATS-PFM-LLM-007-07, ATS-PFM-LLM-007-16, TST-PFM-LLM-019
invariantservice, databaseobserved
services-platform:modules/llm/services/persistence/allowance-periods.ts
09must prove
Proposed
Charged usage includes request settlements and signed corrections, while available credits subtract both charged usage and outstanding holds from the allowance.
proved by ATS-PFM-LLM-007-08, ATS-PFM-LLM-007-11, ATS-PFM-LLM-007-12, ATS-PFM-LLM-007-13, ATS-PFM-LLM-007-14, ATS-PFM-LLM-007-18, ATS-PFM-LLM-007-19, TST-PFM-LLM-046
calculationservice, databaseobserved
services-platform:modules/llm/services/persistence/allowance-periods.ts
10must prove
Proposed
A refusal retains its decision-time allowance, committed and needed credits, active capacity, limits version, concurrency and switches once, without prompt or person content.
proved by ATS-PFM-LLM-007-09, TST-PFM-LLM-018, TST-PFM-LLM-078
invariantservice, databaseobserved
services-platform:modules/llm/services/metering/refusal-snapshot.ts
11
Proposed
The allowance covers the organization as a whole and has no departmental or cost-centre allocations.
origin: services-platform:docs/debt/llm-cost-centre-allowances.md
policyservicedocumented
services-platform:docs/llm.md#What is deliberately not here

Scenarios

IdGivenWhenThenProvenance
01Concurrent requests compete for capacity sufficient for fifteen reservations.Twenty requests attempt admission.Fifteen reservations succeed and five are refused for allowance capacity.test
services-platform:modules/llm/tests/integration/lifecycle/llm-ledger-concurrency.integration.spec.js#refuses the other five as the allowance being spent, not as the cap
02The remaining credit balance is smaller than the next request’s maximum reservation.A person submits that request.Admission refuses it despite a positive remaining balance.documented
services-platform:docs/milestones/plans/PLAT-M1-plan.md#D1. When is an organization's allowance "used up"?

Edge Cases

IdGivenWhenThenProvenance
03A temporary grant reaches its end time.A new request attempts admission.The expired grant contributes no capacity.test
services-platform:modules/llm/tests/integration/lifecycle/llm-ledger-concurrency.integration.spec.js#refuses it as the allowance being spent, with no override left in force

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