---
id: STATE-PFM-LLM-006
title: Threshold crossing and its notice
object: DOM-PFM-LLM-003
product_area: platform
module: llm
revision: 1
status: draft
design_intent: proposed
origin: >-
  Recipients follow D-4 (Andrew, 2026-10-18, the built-in Administrator role for now); the claim, lease and
  retry mechanics are the PLAT-M1 plan's, which awaits approval
  (services-platform:docs/proposals/llm-observability/11-decisions.md#Decision record).
implementation_evidence: observed
source_sha:
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
states:
  - name: absent
    meaning: No crossing has been recorded for this month and threshold.
  - name: owed
    meaning: A crossing remains unstamped and is eligible for another claim when its lease allows.
  - name: leased
    meaning: A sender has claimed an attempt within its ten-minute lease.
  - name: delivered
    meaning: 'The completion stamp records recipients handled, including policy-suppressed sends.'
  - name: nobody_told
    meaning: The crossing was completed with zero eligible administrators.
  - name: given_up
    meaning: The unstamped crossing has exhausted its three allowed claims.
transitions:
  - from: absent
    to: owed
    trigger: A settlement reaches a charged-usage threshold.
    guard: 'No row already exists for this organization, month and threshold.'
    side_effects:
      - 'Persist the crossing figures, then attempt immediate delivery outside an enclosing transaction.'
    who: LLM foundation runtime or hourly reconciliation
    provenance: observed
    source: 'services-platform:modules/llm/services/metering/llm-credit-ledger.ts:evaluateCrossings'
  - from: owed
    to: leased
    trigger: A sender tries to claim the recorded crossing.
    guard: 'It is unstamped, below three claims and outside a live ten-minute lease.'
    side_effects:
      - Stamp claim time and increment attempts.
    who: LLM foundation runtime or hourly reconciliation
    provenance: observed
    source: 'services-platform:modules/llm/services/persistence/allowance-periods.ts:claimThresholdNotice'
  - from: leased
    to: delivered
    trigger: At least one recipient is handled successfully or suppressed by delivery policy.
    guard: The crossing is still unstamped.
    side_effects:
      - Record completion time and handled-recipient count; do not retry partial failures.
    who: LLM foundation runtime or hourly reconciliation
    provenance: observed
    source: 'services-platform:modules/llm/services/persistence/allowance-periods.ts:stampThresholdNotified'
  - from: leased
    to: nobody_told
    trigger: The recipient resolver returns no eligible administrators.
    guard: The crossing is still unstamped.
    side_effects:
      - Stamp completion with zero recipients and log the missing audience.
    who: LLM foundation runtime or hourly reconciliation
    provenance: observed
    source: 'services-platform:modules/llm/services/notices/threshold-notice.ts:sendThresholdNotice'
  - from: leased
    to: owed
    trigger: Nobody is reached or the sender stops and the lease expires.
    guard: Fewer than three claims have been taken.
    side_effects:
      - Make the row eligible for hourly retry; logged failures contribute operational metrics.
    who: 'Time, then the hourly reconciliation'
    provenance: observed
    source: 'services-platform:modules/llm/services/notices/retry-threshold-notices.ts:retryThresholdNotices'
  - from: leased
    to: given_up
    trigger: The last allowed claim ends without completion.
    guard: Three claims have been recorded and the crossing remains unstamped.
    side_effects:
      - Leave the row visible without another automatic claim.
    who: Hourly reconciliation
    provenance: observed
    source: 'services-platform:modules/llm/services/persistence/allowance-periods.ts:claimThresholdNotice'
  - from: leased
    to: leased
    trigger: Delivery occurred but completion was not recorded before lease expiry.
    guard: The row is unstamped and still below the attempt limit.
    side_effects:
      - A later claim may send duplicate copies.
    who: Hourly reconciliation
    provenance: observed
    source: 'services-platform:modules/llm/services/notices/threshold-notice.ts:sendThresholdNotice'
invalid:
  - from: delivered
    to: leased
    why: A completion stamp excludes another claim.
  - from: given_up
    to: leased
    why: Three recorded attempts exclude another claim.
  - from: absent
    to: leased
    why: >-
      Claiming requires an existing crossing; holds, corrections and allowance reductions create no crossing
      here.
  - from: nobody_told
    to: delivered
    why: A zero-recipient completion prevents later retry when administrators are appointed.
concurrency: >-
  A claim excludes competitors only until its ten-minute lease expires. A slow sender can overlap a successor,
  and the completion stamp does not require lease ownership. The three-attempt limit permits missing delivery
  as well as duplicates.
invariants:
  - INV-DOM-PFM-LLM-003-11
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 (recordThresholdCrossing, claimThresholdNotice,
    stampThresholdNotified, listOwedThresholdNotices); db/llm-usage-threshold-crossings.table.ts;
    llm.settings.ts; lib/notices/send-notice.ts, recipients.ts (shared helpers, read to name them).
---

# Threshold crossing and its notice

## The Lifecycle

```mermaid
stateDiagram-v2
  absent --> owed
  owed --> leased
  leased --> delivered
  leased --> nobody_told
  leased --> owed
  leased --> given_up
  leased --> leased
```

## Transitions Explained

Crossings record charged usage reaching eighty or one hundred percent and also carry notice bookkeeping. Senders claim before resolving administrators and sending messages. Success or policy suppression stamps the number handled; no eligible administrators stamps zero. An unstamped row can retry until its claim budget is spent.

## What Cannot Happen

Completed crossings are not claimable again. Neither held capacity nor a correction creates a threshold notice through this path. Exhausted attempts remain visible rather than being silently marked delivered.

## Concurrency and Timing

Sending follows committed crossing creation. If the caller is already in a transaction, immediate sending is deferred to reconciliation. Failure between delivery and stamping can cause duplicate messages; failure between settlement and crossing creation can leave a notice absent until another settlement.