--- id: WF-PFM-LLM-005 title: Tell administrators an allowance threshold was crossed trigger: Attempt threshold email after recording a charged-usage crossing. product_area: platform module: llm revision: 1 status: draft design_intent: proposed origin: >- D-4 (Andrew, 2026-10-18): the organization's Administrator role holders at 80% and 100%, for now, until responsibilities exist (services-platform:docs/proposals/llm-observability/11-decisions.md#Decision record). implementation_evidence: observed inference: [] source_sha: services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 implements: - CAP-PFM-LLM-008 - CAP-PFM-LLM-018 moves: - STATE-PFM-LLM-006 crosses: - SVC-PFM-LLM-llm idempotency: >- Uniqueness protects crossing creation and conditional claims bound retries. Delivering before stamping allows duplicates and the attempt ceiling allows no delivery. concurrency: >- A ten-minute claim excludes competing claims until expiry; a slow sender can overlap a successor and completion does not check lease ownership. hops: - 'n': 1 actor_or_service: Credit ledger (after a settlement) action: Insert the month-and-threshold crossing from settled charges and current capacity. anchor: 'services-platform:modules/llm/services/persistence/allowance-periods.ts:recordThresholdCrossing' seam: sync on_failure: Propagate crossing-write failure to the settlement caller. left_inconsistent: A missing crossing may be detected by a later settlement. observer: 'Crossing bookkeeping, delivery logs and notice-failure metrics.' provenance: observed source: 'services-platform:modules/llm/services/metering/llm-credit-ledger.ts:evaluateCrossings' - 'n': 2 actor_or_service: Credit ledger (after a settlement) action: Attempt delivery after crossing commit unless an enclosing transaction remains open. anchor: 'services-platform:modules/llm/services/metering/llm-credit-ledger.ts:evaluateCrossings' seam: sync on_failure: Log start failures without failing settlement. left_inconsistent: The crossing remains eligible for reconciliation. observer: 'Crossing bookkeeping, delivery logs and notice-failure metrics.' 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 - 'n': 3 actor_or_service: Threshold notice sender action: Conditionally claim an unstamped crossing within its attempt budget. anchor: 'services-platform:modules/llm/services/persistence/allowance-periods.ts:claimThresholdNotice' seam: sync on_failure: Log and measure failures; losing a claim performs no send. left_inconsistent: A recorded claim can remain until its ten-minute lease expires. observer: 'Crossing bookkeeping, delivery logs and notice-failure metrics.' provenance: observed source: 'services-platform:modules/llm/services/notices/threshold-notice.ts:sendThresholdNotice' - 'n': 4 actor_or_service: Threshold notice sender and Security role holders action: Resolve eligible Administrator role holders and complete a zero-recipient crossing when none exist. anchor: 'services-platform:lib/notices/recipients.ts:administratorRecipients' seam: sync on_failure: Log resolution or stamping failure for later eligible retry. left_inconsistent: The audience can remain untold; zero-recipient completion is permanent. observer: 'Crossing bookkeeping, delivery logs and notice-failure metrics.' provenance: observed source: 'services-platform:modules/llm/services/notices/threshold-notice.ts:sendThresholdNotice' - 'n': 5 actor_or_service: Shared e-mail sender action: 'Send each administrator the retained usage figures, reset date and support guidance.' anchor: 'services-platform:lib/notices/send-notice.ts:sendNoticeToRecipients' seam: sync on_failure: Count recipient failures; leave all-failed sends unstamped. left_inconsistent: Partial success completes the crossing without retrying unsuccessful recipients. observer: 'Crossing bookkeeping, delivery logs and notice-failure metrics.' provenance: observed source: 'services-platform:modules/llm/services/notices/threshold-notice.ts:buildThresholdNotice' - 'n': 6 actor_or_service: Threshold notice sender action: Record completion time and the recipients sent or suppressed by policy. anchor: 'services-platform:modules/llm/services/persistence/allowance-periods.ts:stampThresholdNotified' seam: sync on_failure: Log and measure a failed completion stamp. left_inconsistent: Already sent messages can be repeated by a later claimant. observer: 'Crossing bookkeeping, delivery logs and notice-failure metrics.' provenance: observed source: 'services-platform:modules/llm/services/notices/threshold-notice.ts:sendThresholdNotice' - 'n': 7 actor_or_service: Hourly reconciliation function action: Reconciliation retries up to twenty owed notices per operational organization. anchor: 'services-platform:modules/llm/services/notices/retry-threshold-notices.ts:retryThresholdNotices' seam: schedule on_failure: Continue after organization failure; exhausted crossings receive no further claims. left_inconsistent: An exhausted crossing remains unstamped for staff inspection. observer: 'Crossing bookkeeping, delivery logs and notice-failure metrics.' provenance: observed source: 'services-platform:modules/llm/services/persistence/allowance-periods.ts:listOwedThresholdNotices' branches: - The structured hops retain the applicable alternative path and its failure boundary. waits: - 'Unstamped notices become claimable after a ten-minute lease, until three claims are recorded.' evidence: - >- services-platform at ad3f6a6: modules/llm/services/metering/llm-credit-ledger.ts; services/notices/threshold-notice.ts, retry-threshold-notices.ts; services/persistence/allowance-periods.ts; services/usage/usage-sentences.ts; lib/notices/recipients.ts, send-notice.ts; aws/logic/llm-reconciliation.lambda.ts (LlmNoticesFailedAlarm); docs/llm.md#Notices; docs/notifications.md (the Platform notification pipeline these notices do not use). controls: [TC-AVL-001, TC-AVL-004, TC-AVL-005, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-CHG-001, TC-CHG-002, TC-CHG-003, TC-CHG-004, TC-CHG-005, TC-CHG-006, TC-CHG-007, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-IAM-001, TC-IAM-002, TC-IAM-004, TC-IAM-005, TC-IAM-006, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-MON-001, TC-MON-002, TC-MON-003, 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] --- # Tell administrators an allowance threshold was crossed ## What It Does Administrator recipients receive retained crossing figures and the local reset explanation. The crossing row tracks claims and completion. ## The Flow ```mermaid flowchart TD H1["Insert the month-and-threshold crossing from settled charges and current capacity."] H2["Attempt delivery after crossing commit unless an enclosing transaction remains open."] H1 --> H2 H3["Conditionally claim an unstamped crossing within its attempt budget."] H2 --> H3 H4["Resolve eligible Administrator role holders and complete a zero-recipient crossing when none exist."] H3 --> H4 H5["Send each administrator the retained usage figures, reset date and support guidance."] H4 --> H5 H6["Record completion time and the recipients sent or suppressed by policy."] H5 --> H6 H7["Reconciliation retries up to twenty owed notices per operational organization."] H6 --> H7 ``` Claim before resolving recipients and sending; stamp recipients handled after delivery. Reconciliation retries eligible unstamped rows. ## When Something Fails Partial success completes the notice without retrying failed recipients. Zero recipients completes with zero. Three unsuccessful claims leave it owed without further automatic delivery, and expired leases permit duplicates. ## Open Design Questions The interim recipient decision is already recorded; the remaining question is migration to responsibility-based notification handling.