---
id: CAP-PFM-LLM-007
title: Admit AI work against the organization’s monthly allowance
feature: FEAT-PFM-LLM-03
product_area: platform
module: llm
revision: 1
status: draft
product_intent: proposed
implementation_evidence: observed
supersedes: []
source_sha:
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
intent_sources:
  - 'services-platform:docs/proposals/llm-observability/11-decisions.md#D-3'
  - 'services-platform:docs/proposals/llm-observability/11-decisions.md#D-6'
  - 'services-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)'
purpose: Control new AI spending using one allowance shared across the customer’s workspace.
outcomes:
  - Admission rejects requests whose reservation does not fit.
  - A concurrency cap restricts simultaneous admitted requests.
  - Dated grants affect capacity only while active.
concepts:
  - CON-PFM-LLM-003
  - CON-PFM-LLM-001
actors:
  - ACT-PFM-032
  - ACT-PFM-012
surfaces:
  - api
  - job
preconditions:
  - Organization and operation switches permit admission.
postconditions:
  - Admission records either a reservation or its refusal figures.
permissions: []
rules:
  - id: BR-CAP-PFM-LLM-007-01
    proved_by: [ATS-PFM-LLM-007-01, ATS-PFM-LLM-007-21, TST-PFM-LLM-030, TST-PFM-LLM-062]
    statement: >-
      The organization receives one allowance period per local calendar month, created on demand with its
      configured allowance or the default 100,000 credits.
    kind: calculation
    enforced_at:
      - service
      - database
    must_prove: true
    provenance: observed
    source: 'services-platform:modules/llm/services/persistence/allowance-periods.ts'
    origin: none
    examples:
      positive: An organization in Eastern time starts a new period at midnight on the first in its own zone.
      negative: Nothing has to run at month end for the allowance to start over.
  - id: BR-CAP-PFM-LLM-007-02
    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]
    statement: >-
      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.
    kind: calculation
    enforced_at:
      - service
      - database
    must_prove: true
    provenance: observed
    source: 'services-platform:modules/llm/services/persistence/allowance-periods.ts'
    origin: none
  - id: BR-CAP-PFM-LLM-007-03
    proved_by: [ATS-PFM-LLM-001-16, ATS-PFM-LLM-007-03, TST-PFM-LLM-020]
    statement: >-
      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.
    kind: policy
    enforced_at:
      - service
    must_prove: true
    provenance: observed
    source: 'services-platform:modules/llm/services/execution/run-operation.ts'
    origin: none
  - id: BR-CAP-PFM-LLM-007-04
    proved_by: [ATS-PFM-LLM-007-04, TST-PFM-LLM-019]
    statement: >-
      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.
    kind: policy
    enforced_at:
      - service
      - database
    must_prove: true
    provenance: test
    source: >-
      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
    origin: none
  - id: BR-CAP-PFM-LLM-007-05
    proved_by: [ATS-PFM-LLM-007-04, TST-PFM-LLM-019]
    statement: 'When allowance and concurrency would both reject admission, the refusal reports the allowance.'
    kind: policy
    enforced_at:
      - service
    must_prove: true
    provenance: test
    source: >-
      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
    origin: none
  - id: BR-CAP-PFM-LLM-007-06
    proved_by: [ATS-PFM-LLM-007-05, ATS-PFM-LLM-007-17, TST-PFM-LLM-019]
    statement: >-
      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.
    kind: calculation
    enforced_at:
      - service
      - database
    must_prove: true
    provenance: observed
    source: 'services-platform:modules/llm/services/persistence/allowance-periods.ts'
    origin: none
  - id: BR-CAP-PFM-LLM-007-07
    proved_by: [ATS-PFM-LLM-007-06, TST-PFM-LLM-005]
    statement: Already admitted work is charged its measured usage even if the period exceeds its allowance.
    kind: calculation
    enforced_at:
      - service
    must_prove: true
    provenance: observed
    source: 'services-platform:modules/llm/services/execution/run-operation.ts'
    origin: none
  - id: BR-CAP-PFM-LLM-007-08
    proved_by: [ATS-PFM-LLM-007-07, ATS-PFM-LLM-007-16, TST-PFM-LLM-019]
    statement: >-
      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.
    kind: invariant
    enforced_at:
      - service
      - database
    must_prove: true
    provenance: observed
    source: 'services-platform:modules/llm/services/persistence/allowance-periods.ts'
    origin: none
  - id: BR-CAP-PFM-LLM-007-09
    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]
    statement: >-
      Charged usage includes request settlements and signed corrections, while available credits subtract both
      charged usage and outstanding holds from the allowance.
    kind: calculation
    enforced_at:
      - service
      - database
    must_prove: true
    provenance: observed
    source: 'services-platform:modules/llm/services/persistence/allowance-periods.ts'
    origin: none
  - id: BR-CAP-PFM-LLM-007-10
    proved_by: [ATS-PFM-LLM-007-09, TST-PFM-LLM-018, TST-PFM-LLM-078]
    statement: >-
      A refusal retains its decision-time allowance, committed and needed credits, active capacity, limits
      version, concurrency and switches once, without prompt or person content.
    kind: invariant
    enforced_at:
      - service
      - database
    must_prove: true
    provenance: observed
    source: 'services-platform:modules/llm/services/metering/refusal-snapshot.ts'
    origin: none
  - id: BR-CAP-PFM-LLM-007-11
    proved_by: []
    statement: The allowance covers the organization as a whole and has no departmental or cost-centre allocations.
    kind: policy
    enforced_at:
      - service
    must_prove: false
    provenance: documented
    source: 'services-platform:docs/llm.md#What is deliberately not here'
    origin: 'services-platform:docs/debt/llm-cost-centre-allowances.md'
scenarios:
  - id: SC-CAP-PFM-LLM-007-01
    given: Concurrent requests compete for capacity sufficient for fifteen reservations.
    when: Twenty requests attempt admission.
    then: Fifteen reservations succeed and five are refused for allowance capacity.
    provenance: test
    source: >-
      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
  - id: SC-CAP-PFM-LLM-007-02
    given: The remaining credit balance is smaller than the next request’s maximum reservation.
    when: A person submits that request.
    then: Admission refuses it despite a positive remaining balance.
    provenance: documented
    source: >-
      services-platform:docs/milestones/plans/PLAT-M1-plan.md#D1. When is an organization's allowance "used
      up"?
edge_cases:
  - id: SC-CAP-PFM-LLM-007-03
    given: A temporary grant reaches its end time.
    when: A new request attempts admission.
    then: The expired grant contributes no capacity.
    provenance: test
    source: >-
      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
constraints:
  - >-
    The meaning of an exhausted allowance needs a product decision when some credits remain but a reservation
    cannot fit.
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
journeys:
  - JNY-PFM-LLM-001
  - JNY-PFM-LLM-003
open_questions:
  - OQ-PFM-LLM-001
evidence:
  - >-
    services-platform at ad3f6a6582843008ed0f5a17b131878d15829af1: docs/llm.md (Money, The predicate, The
    refusal snapshot); docs/milestones/PLAT-M1-ai-usage-metered-and-visible.md; plans/PLAT-M1-plan.md (A4, A7
    to A9, D1); docs/proposals/llm-observability/11-decisions.md (D-3, D-6); modules/llm/llm.settings.ts;
    services/persistence/allowance-periods.ts; services/metering/llm-credit-ledger.ts, refusal-snapshot.ts;
    db/llm-allowance-periods.table.ts; tests integration/lifecycle/llm-ledger-concurrency.integration.spec.js,
    integration/services/persistence/allowance-periods.integration.spec.js,
    lifecycle/run-operation.integration.spec.js, lifecycle/executions.integration.spec.js,
    e2e/allowance-warning.e2e.spec.js, unit/services/refusal-snapshot.spec.ts.
controls: [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]
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]
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]
---

# 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.