--- id: CAP-PFM-LLM-008 title: Notify administrators at allowance thresholds 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-4' - 'services-platform:docs/milestones/PLAT-M1-ai-usage-metered-and-visible.md#D-4 (proposal)' purpose: Give customer administrators a recorded warning as charged AI usage approaches and reaches its allowance. outcomes: - Recorded crossings drive administrator warning and pause notices. - Recipients exclude other workspace staff. - Failed notice delivery has bounded retry attempts. concepts: - CON-PFM-LLM-003 actors: - ACT-PFM-007 - ACT-PFM-012 surfaces: - job preconditions: - Charged usage has crossed a notice threshold. postconditions: - 'Crossing history records delivery attempts, completion and recipients.' permissions: [] rules: - id: BR-CAP-PFM-LLM-008-01 proved_by: [ATS-PFM-LLM-007-11, ATS-PFM-LLM-008-01, TST-PFM-LLM-030] statement: >- Charged usage reaching 80% or 100% records one crossing for that threshold and month despite concurrent settlements; held credits do not create crossings. kind: lifecycle 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-008-02 proved_by: [ATS-PFM-LLM-008-02] statement: >- Threshold evaluation uses whole-number arithmetic over charged credits and allowance including currently active additional capacity. kind: calculation enforced_at: - service must_prove: true provenance: observed source: 'services-platform:modules/llm/services/metering/llm-credit-ledger.ts:evaluateCrossings' origin: none - id: BR-CAP-PFM-LLM-008-03 proved_by: [ATS-PFM-LLM-008-03, TST-PFM-LLM-005, TST-PFM-LLM-028] statement: >- Each active holder of the organization’s built-in Administrator role receives one notice, excluding suspended holders, other staff and administrators of other organizations. kind: policy enforced_at: - service must_prove: true provenance: test source: >- 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 origin: 'services-platform:docs/proposals/llm-observability/11-decisions.md#D-4' - id: BR-CAP-PFM-LLM-008-04 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] statement: >- 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. kind: calculation enforced_at: - service must_prove: true provenance: observed source: 'services-platform:modules/llm/services/notices/threshold-notice.ts' origin: none - id: BR-CAP-PFM-LLM-008-05 proved_by: [ATS-PFM-LLM-008-05, TST-PFM-LLM-028] statement: >- An unsent crossing can be claimed only below three attempts and outside a ten-minute live claim, giving racing senders one delivery owner. 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-008-06 proved_by: [ATS-PFM-LLM-008-06, TST-PFM-LLM-028] statement: >- Settlement sends only after its own transaction commits; an enclosing open transaction leaves the notice pending for reconciliation. kind: policy enforced_at: - service must_prove: true provenance: test source: >- services-platform:modules/llm/tests/integration/services/notices/threshold-notice.integration.spec.js#sends nothing from inside a transaction, leaving the crossing owed origin: none - id: BR-CAP-PFM-LLM-008-07 proved_by: [ATS-PFM-LLM-008-07, ATS-PFM-LLM-008-10, ATS-PFM-LLM-008-11, TST-PFM-LLM-028] statement: >- 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. kind: lifecycle enforced_at: - service - database must_prove: true provenance: observed source: 'services-platform:modules/llm/services/notices/threshold-notice.ts' origin: none - id: BR-CAP-PFM-LLM-008-08 proved_by: [ATS-PFM-LLM-008-08, TST-PFM-LLM-028] statement: >- A crossing without administrator recipients is stamped with zero recipients and logged as a warning without further retries. kind: policy enforced_at: - service must_prove: true provenance: observed source: 'services-platform:modules/llm/services/notices/threshold-notice.ts' origin: none - id: BR-CAP-PFM-LLM-008-09 proved_by: [] statement: >- Nonproduction email delivery follows the test-mailbox and allow-list policy, and environment-withheld messages count as handled. kind: policy enforced_at: - service must_prove: false provenance: documented source: 'services-platform:docs/llm.md#Notices' origin: none - id: BR-CAP-PFM-LLM-008-10 proved_by: [ATS-PFM-LLM-008-12] statement: >- Corrections and allowance reductions do not trigger threshold notices even when they move usage beyond a threshold. kind: policy enforced_at: - service must_prove: false provenance: documented source: 'services-platform:docs/milestones/plans/PLAT-M1-plan.md#4. Assumptions' origin: none - id: BR-CAP-PFM-LLM-008-11 proved_by: [] statement: Notice failures contribute a metric whose alarm triggers above three failures in fifteen minutes. kind: policy enforced_at: - service must_prove: false provenance: documented source: 'services-platform:docs/llm.md#Notices' origin: none - id: BR-CAP-PFM-LLM-008-12 proved_by: [ATS-PFM-LLM-008-09] statement: >- 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. kind: lifecycle enforced_at: - service must_prove: true provenance: observed source: 'services-platform:modules/llm/services/notices/threshold-notice.ts:sendThresholdNotice' origin: none scenarios: - id: SC-CAP-PFM-LLM-008-01 given: Two administrators share a workspace with other staff. when: Successive requests cross warning and pause thresholds. then: >- The tested sequence sends administrator notices without notifying other staff or repeating notices for refusals. provenance: test source: >- services-platform:modules/llm/tests/e2e/allowance-warning.e2e.spec.js#tells nobody anything more for a refused call - id: SC-CAP-PFM-LLM-008-02 given: A crossing belongs to a workspace without administrators. when: Notice processing resolves its recipients. then: The crossing is completed with zero recipients and receives no retry. provenance: test source: >- services-platform:modules/llm/tests/integration/services/notices/threshold-notice.integration.spec.js#answers that there was nobody to tell and sends nothing edge_cases: [] constraints: - Administrator recipients are the current arrangement; responsibility-based recipients remain proposed. depends_on: - CAP-PFM-LLM-007 related: - CAP-PFM-LLM-009 - CAP-PFM-LLM-011 - CAP-PFM-LLM-018 journeys: - JNY-PFM-LLM-001 open_questions: - OQ-PFM-LLM-001 - OQ-PFM-LLM-002 evidence: - >- services-platform at ad3f6a6582843008ed0f5a17b131878d15829af1: docs/llm.md (Notices); docs/milestones/plans/PLAT-M1-plan.md (A5, A10, A11, D2); modules/llm/services/notices/threshold-notice.ts, retry-threshold-notices.ts; services/metering/llm-credit-ledger.ts (evaluateCrossings); db/llm-usage-threshold-crossings.table.ts; tests integration/services/notices/threshold-notice.integration.spec.js, e2e/allowance-warning.e2e.spec.js, unit/services/threshold-notice.spec.ts. The recipient resolver and sender (lib/notices) are shared Platform code named as a dependency. controls: [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] 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-028, TST-PFM-LLM-030, TST-PFM-LLM-080] --- # 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.