Rhythm 2.0 Specifications

Appearance

CAP-PFM-LLM-008Notify administrators at allowance thresholds

Markdown

CAP-PFM-LLM-008

Notify administrators at allowance thresholds

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, JNY-PFM-LLM-004
Key concepts
CON-PFM-LLM-003
Actors
ACT-PFM-007, ACT-PFM-012
Journeys
JNY-PFM-LLM-001
Depends on
CAP-PFM-LLM-007
Related
CAP-PFM-LLM-009, CAP-PFM-LLM-011, CAP-PFM-LLM-018
Open questions
OQ-PFM-LLM-001, OQ-PFM-LLM-002
Proved by
ATS-PFM-LLM-008

Implementation

Executable suites
TST-PFM-LLM-005, TST-PFM-LLM-028, TST-PFM-LLM-030, TST-PFM-LLM-080

KindCapabilityProduct areaPlatformModuleAI Requests, Usage and the Jazz AI TeammateRevision1

Read atservices-platform ad3f6a65

Notify administrators at allowance thresholds ​

Purpose ​

Give customer administrators a recorded warning as charged AI usage approaches and reaches its allowance.

How It Works ​

Settlement checks whether charged usage has crossed a notice threshold. The crossing record preserves the figures that support that notice. A sender claims the crossing before resolving the organization’s active administrators. Each recipient receives an individual message. The warning and pause messages use credit figures and the organization’s reset date. An enclosing transaction defers delivery to reconciliation rather than sending before commitment. Failed delivery retries within a bounded attempt policy, while the no-administrator case is recorded explicitly. The product should settle the interim recipient responsibility and the meaning of a paused notice before broader release.

Relationships ​

  • Admit AI work against the organization’s monthly allowance 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
Recorded crossings drive administrator warning and pause notices.Recipients exclude other workspace staff.Failed notice delivery has bounded retry attempts.
Surfaces
job
Preconditions
Charged usage has crossed a notice threshold.
Postconditions
Crossing history records delivery attempts, completion and recipients.
Constraints
Administrator recipients are the current arrangement; responsibility-based recipients remain proposed.
Intent sources
services-platform:docs/proposals/llm-observability/11-decisions.md#D-4services-platform:docs/milestones/PLAT-M1-ai-usage-metered-and-visible.md#D-4 (proposal)

Controls

29 controls apply, from the corpus control catalogue.

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

Business Rules

12 rules, 9 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
Charged usage reaching 80% or 100% records one crossing for that threshold and month despite concurrent settlements; held credits do not create crossings.
proved by ATS-PFM-LLM-007-11, ATS-PFM-LLM-008-01, TST-PFM-LLM-030
lifecycleservice, databaseobserved
services-platform:modules/llm/services/persistence/allowance-periods.ts
02must prove
Proposed
Threshold evaluation uses whole-number arithmetic over charged credits and allowance including currently active additional capacity.
proved by ATS-PFM-LLM-008-02
calculationserviceobserved
services-platform:modules/llm/services/metering/llm-credit-ledger.ts:evaluateCrossings
03must prove
Proposed
Each active holder of the organization’s built-in Administrator role receives one notice, excluding suspended holders, other staff and administrators of other organizations.
origin: services-platform:docs/proposals/llm-observability/11-decisions.md#D-4
proved by ATS-PFM-LLM-008-03, TST-PFM-LLM-005, TST-PFM-LLM-028
policyservicetest
services-platform:modules/llm/tests/integration/services/notices/threshold-notice.integration.spec.js#sends one message to each administrator, and to neither the suspended one nor the administrator of another organization
04must prove
Proposed
The warning provides used, allowed and remaining credits, the local reset date, the 100% consequence and support contact; the pause notice names the reset date and shares the customer pause wording.
proved by ATS-PFM-LLM-008-04, ATS-PFM-LLM-008-13, ATS-PFM-LLM-008-14, TST-PFM-LLM-005, TST-PFM-LLM-028, TST-PFM-LLM-080
calculationserviceobserved
services-platform:modules/llm/services/notices/threshold-notice.ts
05must prove
Proposed
An unsent crossing can be claimed only below three attempts and outside a ten-minute live claim, giving racing senders one delivery owner.
proved by ATS-PFM-LLM-008-05, TST-PFM-LLM-028
invariantservice, databaseobserved
services-platform:modules/llm/services/persistence/allowance-periods.ts
06must prove
Proposed
Settlement sends only after its own transaction commits; an enclosing open transaction leaves the notice pending for reconciliation.
proved by ATS-PFM-LLM-008-06, TST-PFM-LLM-028
policyservicetest
services-platform:modules/llm/tests/integration/services/notices/threshold-notice.integration.spec.js#sends nothing from inside a transaction, leaving the crossing owed
07must prove
Proposed
Zero successful deliveries leave the crossing unstamped for hourly retry up to three attempts; partial success stamps the successful-recipient count, and three failures leave an unresolved crossing.
proved by ATS-PFM-LLM-008-07, ATS-PFM-LLM-008-10, ATS-PFM-LLM-008-11, TST-PFM-LLM-028
lifecycleservice, databaseobserved
services-platform:modules/llm/services/notices/threshold-notice.ts
08must prove
Proposed
A crossing without administrator recipients is stamped with zero recipients and logged as a warning without further retries.
proved by ATS-PFM-LLM-008-08, TST-PFM-LLM-028
policyserviceobserved
services-platform:modules/llm/services/notices/threshold-notice.ts
09
Proposed
Nonproduction email delivery follows the test-mailbox and allow-list policy, and environment-withheld messages count as handled.
policyservicedocumented
services-platform:docs/llm.md#Notices
10
Proposed
Corrections and allowance reductions do not trigger threshold notices even when they move usage beyond a threshold.
proved by ATS-PFM-LLM-008-12
policyservicedocumented
services-platform:docs/milestones/plans/PLAT-M1-plan.md#4. Assumptions
11
Proposed
Notice failures contribute a metric whose alarm triggers above three failures in fifteen minutes.
policyservicedocumented
services-platform:docs/llm.md#Notices
12must prove
Proposed
A notice is delivered before its completion stamp is saved. If processing stops between those actions, a later attempt can deliver the same crossing again.
proved by ATS-PFM-LLM-008-09
lifecycleserviceobserved
services-platform:modules/llm/services/notices/threshold-notice.ts:sendThresholdNotice

Scenarios

IdGivenWhenThenProvenance
01Two administrators share a workspace with other staff.Successive requests cross warning and pause thresholds.The tested sequence sends administrator notices without notifying other staff or repeating notices for refusals.test
services-platform:modules/llm/tests/e2e/allowance-warning.e2e.spec.js#tells nobody anything more for a refused call
02A crossing belongs to a workspace without administrators.Notice processing resolves its recipients.The crossing is completed with zero recipients and receives no retry.test
services-platform:modules/llm/tests/integration/services/notices/threshold-notice.integration.spec.js#answers that there was nobody to tell and sends nothing

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