--- id: ATS-PFM-LLM-008 scope: CAP-PFM-LLM-008 product_area: platform module: llm revision: 2 status: proposed source_sha: services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 scenarios: - id: ATS-PFM-LLM-008-01 title: Threshold records remain unique under races level: api proves: - BR-CAP-PFM-LLM-008-01 - INV-DOM-PFM-LLM-003-11 preconditions: Settlements and recording calls approach both notice thresholds. steps: Cross and concurrently record each threshold. expected: Exactly one record and one successful recording caller exist per threshold. negative: false data_needs: Fixtures representing settlements and recording calls approach both notice thresholds. bound_to: - TST-PFM-LLM-030 provenance: test source: >- services-platform:modules/llm/tests/integration/services/persistence/allowance-periods.integration.spec.js#answers false the second time rather than notifying again category: concurrency test_sources: - >- services-platform:modules/llm/tests/integration/services/persistence/allowance-periods.integration.spec.js#answers false the second time rather than notifying again - >- services-platform:modules/llm/tests/integration/services/persistence/allowance-periods.integration.spec.js#tells exactly one caller it recorded the crossing - >- services-platform:modules/llm/tests/integration/services/persistence/allowance-periods.integration.spec.js#records the 100% crossing separately, because it is a different thing to say - id: ATS-PFM-LLM-008-02 title: Only charged usage crosses notice thresholds level: api proves: - BR-CAP-PFM-LLM-008-02 preconditions: 'Held usage reaches 80% but charged usage remains below it, with additional capacity active.' steps: Reserve then settle work. expected: >- Reservation creates no crossing; settlement evaluates charged usage against the allowance including active capacity. negative: false data_needs: >- Fixtures representing held usage reaches 80% but charged usage remains below it, with additional capacity active. bound_to: [] provenance: proposed source: 'services-platform:modules/llm/services/metering/llm-credit-ledger.ts:evaluateCrossings' category: rule test_sources: [] - id: ATS-PFM-LLM-008-03 title: Only active local administrators receive notices level: api proves: - BR-CAP-PFM-LLM-008-03 preconditions: 'Active administrators, a suspended holder, other staff and foreign administrators exist.' steps: Trigger the warning. expected: Each eligible local administrator receives one message and everyone else receives none. negative: false data_needs: >- Fixtures representing active administrators, a suspended holder, other staff and foreign administrators exist. bound_to: - TST-PFM-LLM-028 - TST-PFM-LLM-005 provenance: test source: >- services-platform:modules/llm/tests/integration/services/notices/threshold-notice.integration.spec.js#resolves the active holders of the Administrator role, ordered by user id category: permission test_sources: - >- services-platform:modules/llm/tests/integration/services/notices/threshold-notice.integration.spec.js#resolves the active holders of the Administrator role, ordered by user id - >- 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 - >- services-platform:modules/llm/tests/e2e/allowance-warning.e2e.spec.js#never tells a person who is not an administrator - id: ATS-PFM-LLM-008-04 title: Warning and pause messages use customer figures level: api proves: - BR-CAP-PFM-LLM-008-04 preconditions: An organization crosses both notice thresholds. steps: Inspect the generated messages. expected: They state crossing credits and reset information and the pause notice shares the customer explanation. negative: false data_needs: Fixtures representing an organization crosses both notice thresholds. bound_to: - TST-PFM-LLM-028 - TST-PFM-LLM-005 provenance: test source: >- services-platform:modules/llm/tests/integration/services/notices/threshold-notice.integration.spec.js#writes the 80% copy with the figures of the crossing category: rule test_sources: - >- services-platform:modules/llm/tests/integration/services/notices/threshold-notice.integration.spec.js#writes the 80% copy with the figures of the crossing - >- services-platform:modules/llm/tests/e2e/allowance-warning.e2e.spec.js#writes the 80 % notice with what was used and what remains, in the words of the console - >- services-platform:modules/llm/tests/e2e/allowance-warning.e2e.spec.js#writes the 100 % notice with the sentence the console shows - id: ATS-PFM-LLM-008-05 title: Competing senders claim one delivery level: api proves: - BR-CAP-PFM-LLM-008-05 preconditions: Two senders attempt the same crossing. steps: Run both concurrently. expected: One sender claims it and each administrator receives one message. negative: false data_needs: Fixtures representing two senders attempt the same crossing. bound_to: - TST-PFM-LLM-028 provenance: test source: >- services-platform:modules/llm/tests/integration/services/notices/threshold-notice.integration.spec.js#lets exactly one of them claim and send category: concurrency test_sources: - >- services-platform:modules/llm/tests/integration/services/notices/threshold-notice.integration.spec.js#lets exactly one of them claim and send - >- services-platform:modules/llm/tests/integration/services/notices/threshold-notice.integration.spec.js#delivers one message to each of the two administrators, not two each - id: ATS-PFM-LLM-008-06 title: Enclosing transactions defer notice delivery level: api proves: - BR-CAP-PFM-LLM-008-06 preconditions: A settlement crosses a threshold inside a larger transaction. steps: Commit that transaction and run notice retry. expected: Nothing sends inside the transaction; retry later delivers the owed message. negative: false data_needs: Fixtures representing a settlement crosses a threshold inside a larger transaction. bound_to: - TST-PFM-LLM-028 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 category: transition test_sources: - >- services-platform:modules/llm/tests/integration/services/notices/threshold-notice.integration.spec.js#sends nothing from inside a transaction, leaving the crossing owed - >- services-platform:modules/llm/tests/integration/services/notices/threshold-notice.integration.spec.js#has the hourly run send the notice the transaction deferred - id: ATS-PFM-LLM-008-07 title: Persistent delivery failure stops after three attempts level: api proves: - BR-CAP-PFM-LLM-008-07 preconditions: The email sender repeatedly fails and claims expire between runs. steps: 'Send and retry across expired claims, including a fourth eligible run.' expected: The crossing remains unstamped after three failures and no fourth delivery is attempted. negative: true data_needs: Fixtures representing the email sender repeatedly fails and claims expire between runs. bound_to: - TST-PFM-LLM-028 provenance: test source: >- services-platform:modules/llm/tests/integration/services/notices/threshold-notice.integration.spec.js#answers failed when nobody could be reached, and leaves the crossing unstamped category: failure test_sources: - >- services-platform:modules/llm/tests/integration/services/notices/threshold-notice.integration.spec.js#answers failed when nobody could be reached, and leaves the crossing unstamped - >- services-platform:modules/llm/tests/integration/services/notices/threshold-notice.integration.spec.js#does not retry while the first sender’s lease is live - >- services-platform:modules/llm/tests/integration/services/notices/threshold-notice.integration.spec.js#gives up: the fourth run finds nothing owed even with the lease lapsed - >- services-platform:modules/llm/tests/integration/services/notices/threshold-notice.integration.spec.js#leaves the crossing unstamped with its three attempts, which is how HQ finds it - id: ATS-PFM-LLM-008-08 title: No-recipient warnings do not retry forever level: api proves: - BR-CAP-PFM-LLM-008-08 preconditions: A crossing belongs to an organization with no administrator. steps: Attempt delivery. expected: 'The crossing records zero recipients, logs the absence and completes without a sent message.' negative: false data_needs: Fixtures representing a crossing belongs to an organization with no administrator. bound_to: - TST-PFM-LLM-028 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 category: edge test_sources: - >- services-platform:modules/llm/tests/integration/services/notices/threshold-notice.integration.spec.js#answers that there was nobody to tell and sends nothing - >- services-platform:modules/llm/tests/integration/services/notices/threshold-notice.integration.spec.js#stamps the crossing notified with zero recipients - >- services-platform:modules/llm/tests/integration/services/notices/threshold-notice.integration.spec.js#logs a warning that says why - id: ATS-PFM-LLM-008-09 title: A retry can repeat delivery after an interrupted stamp level: api proves: - BR-CAP-PFM-LLM-008-12 preconditions: A crossing has administrator recipients and an unexpired attempt budget. steps: 'Interrupt after email send but before completion persistence, expire the claim and retry.' expected: The same crossing can be delivered again; the product should choose its delivery guarantee. negative: true data_needs: Fault-injection fixtures for the described failure boundary. bound_to: [] provenance: proposed source: 'services-platform:modules/llm/services/notices/threshold-notice.ts:sendThresholdNotice' category: failure test_sources: [] - id: ATS-PFM-LLM-008-10 title: Recovery retries committed owed notices category: interaction level: api proves: - BR-CAP-PFM-LLM-008-07 - BR-CAP-PFM-LLM-009-01 exercises: - CAP-PFM-LLM-008 - CAP-PFM-LLM-009 preconditions: A threshold crossing was deferred by an enclosing transaction that has now committed. steps: Run owed-notice recovery after commit and read crossing history. expected: >- The pending crossing is claimed and delivered under its attempt budget without changing the original charged figures. negative: false data_needs: 'An isolated workspace with the records, clock instants and caller authority stated in the preconditions.' bound_to: - TST-PFM-LLM-028 provenance: test source: - >- services-platform:modules/llm/tests/integration/services/notices/threshold-notice.integration.spec.js#has the hourly run send the notice the transaction deferred test_sources: - >- services-platform:modules/llm/tests/integration/services/notices/threshold-notice.integration.spec.js#has the hourly run send the notice the transaction deferred - id: ATS-PFM-LLM-008-11 title: Inspection shows notice delivery history category: interaction level: api proves: - BR-CAP-PFM-LLM-008-07 - BR-CAP-PFM-LLM-011-10 exercises: - CAP-PFM-LLM-008 - CAP-PFM-LLM-011 preconditions: One crossing has completed delivery and another remains unstamped after failed attempts. steps: Read crossing history from the organization account. expected: >- Each crossing retains its threshold, completion state, recipient count and attempts without turning failure into delivery. negative: true data_needs: 'An isolated workspace with the records, clock instants and caller authority stated in the preconditions.' bound_to: [] provenance: proposed source: - 'services-platform:modules/llm/services/notices/threshold-notice.ts' - 'services-platform:modules/llm/services/usage-reports/tenant-usage.ts' - id: ATS-PFM-LLM-008-12 title: Corrections do not create threshold email category: interaction level: api proves: - BR-CAP-PFM-LLM-008-10 - BR-CAP-PFM-LLM-015-06 exercises: - CAP-PFM-LLM-008 - CAP-PFM-LLM-015 preconditions: Charged usage is below warning and a positive correction moves it above a threshold. steps: Apply the correction and inspect crossings and sent messages. expected: The correction changes usage and audit history but creates no threshold crossing or notice on this path. negative: false data_needs: 'An isolated workspace with the records, clock instants and caller authority stated in the preconditions.' bound_to: [] provenance: proposed source: - 'services-platform:docs/milestones/plans/PLAT-M1-plan.md#4. Assumptions' - 'services-platform:modules/llm/services/adjustments/adjust-allowance.ts' - id: ATS-PFM-LLM-008-13 title: Pause notice shares customer guidance category: interaction level: api proves: - BR-CAP-PFM-LLM-008-04 - BR-CAP-PFM-LLM-018-07 exercises: - CAP-PFM-LLM-008 - CAP-PFM-LLM-018 preconditions: A settlement reaches the pause threshold and the local reset date is known. steps: Generate its notice and the customer pause sentence for the same reset. expected: 'Both give the same renewal and support guidance, allowing the organization-name substitution.' negative: false data_needs: 'An isolated workspace with the records, clock instants and caller authority stated in the preconditions.' bound_to: [] provenance: proposed source: - 'services-platform:modules/llm/services/notices/threshold-notice.ts' - >- services-platform:modules/llm/tests/unit/services/usage/usage-sentences.spec.ts#quote the same at-limit words, the notice naming the organization where the console says "your" - id: ATS-PFM-LLM-008-14 title: Notice copy retains the crossing figures category: rule level: unit proves: - BR-CAP-PFM-LLM-008-04 preconditions: >- The suite owns isolated fixtures representing the valid control and the contrasting case described by its steps. steps: Generate warning copy from a retained crossing and local reset date. expected: 'The message retains used, allowed and remaining credits and renewal guidance.' negative: false data_needs: 'Suite-owned fixtures, with a fixed clock where dates or grant windows matter.' bound_to: - TST-PFM-LLM-080 provenance: test source: >- services-platform:modules/llm/tests/unit/services/threshold-notice.spec.ts#gives credits used, the allowance and what remains, with thousands separators test_sources: - >- services-platform:modules/llm/tests/unit/services/threshold-notice.spec.ts#gives credits used, the allowance and what remains, with thousands separators evidence: - >- services-platform at ad3f6a6582843008ed0f5a17b131878d15829af1: bound or cited modules/llm/services/metering/llm-credit-ledger.ts:evaluateCrossings; modules/llm/tests/e2e/allowance-warning.e2e.spec.js; modules/llm/tests/integration/services/notices/threshold-notice.integration.spec.js; modules/llm/tests/integration/services/persistence/allowance-periods.integration.spec.js. coverage: rule: 'gap: FND-PFM-LLM-067' transition: 'gap: FND-PFM-LLM-067' validation: 'gap: FND-PFM-LLM-067' permission: covered edge: covered failure: covered boundary: 'gap: FND-PFM-LLM-067' concurrency: covered invariant: 'gap: FND-PFM-LLM-067' interaction: covered coverage_notes: transition: >- Existing transition scenarios are retained; the model transition register below records the remaining exhaustive mapping obligation. interaction: >- The related interaction register cites a concrete experiment for every dependency and related capability, including cross-capability workflow seams. rule: >- All must-prove rules have scenario references, but the coverage finding retains untested clauses and combined outcomes; scenario presence alone is not exhaustive rule proof. related_interactions: - with: CAP-PFM-LLM-007 scenarios: - ATS-PFM-LLM-007-11 source: 'services-platform:modules/llm/services/persistence/allowance-periods.ts' - with: CAP-PFM-LLM-009 scenarios: - ATS-PFM-LLM-008-10 source: 'services-platform:modules/llm/aws/lambda/RECONCILIATION.handler.ts' - with: CAP-PFM-LLM-011 scenarios: - ATS-PFM-LLM-008-11 source: >- services-platform:modules/llm/tests/e2e/llm-usage.e2e.spec.js#refuses a customer’s administrator a tenant’s usage even in their own tenant - with: CAP-PFM-LLM-015 scenarios: - ATS-PFM-LLM-008-12 source: >- services-platform:modules/llm/tests/e2e/llm-adjustments-and-organization.e2e.spec.js#is refused 403 for a Support Representative, who holds the read key and not the manage key - with: CAP-PFM-LLM-018 scenarios: - ATS-PFM-LLM-008-13 source: >- services-platform:modules/llm/tests/unit/services/usage/usage-sentences.spec.ts#tells an organization that has used its allowance when it resumes state_models: - STATE-PFM-LLM-006 coverage_obligations: must_prove: - rule: BR-CAP-PFM-LLM-008-01 scenarios: - ATS-PFM-LLM-008-01 source: 'services-platform:modules/llm/services/persistence/allowance-periods.ts' coverage: specified - rule: BR-CAP-PFM-LLM-008-02 scenarios: - ATS-PFM-LLM-008-02 source: 'services-platform:modules/llm/services/metering/llm-credit-ledger.ts:evaluateCrossings' coverage: specified - rule: BR-CAP-PFM-LLM-008-03 scenarios: - ATS-PFM-LLM-008-03 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 coverage: specified - rule: BR-CAP-PFM-LLM-008-04 scenarios: - ATS-PFM-LLM-008-04 - ATS-PFM-LLM-008-13 - ATS-PFM-LLM-008-14 source: 'services-platform:modules/llm/services/notices/threshold-notice.ts' coverage: specified - rule: BR-CAP-PFM-LLM-008-05 scenarios: - ATS-PFM-LLM-008-05 source: 'services-platform:modules/llm/services/persistence/allowance-periods.ts' coverage: partial gap: FND-PFM-LLM-067 - rule: BR-CAP-PFM-LLM-008-06 scenarios: - ATS-PFM-LLM-008-06 source: >- services-platform:modules/llm/tests/integration/services/notices/threshold-notice.integration.spec.js#sends nothing from inside a transaction, leaving the crossing owed coverage: partial gap: FND-PFM-LLM-067 - rule: BR-CAP-PFM-LLM-008-07 scenarios: - ATS-PFM-LLM-008-07 - ATS-PFM-LLM-008-10 - ATS-PFM-LLM-008-11 source: 'services-platform:modules/llm/services/notices/threshold-notice.ts' coverage: partial gap: FND-PFM-LLM-067 - rule: BR-CAP-PFM-LLM-008-08 scenarios: - ATS-PFM-LLM-008-08 source: 'services-platform:modules/llm/services/notices/threshold-notice.ts' coverage: specified - rule: BR-CAP-PFM-LLM-008-12 scenarios: - ATS-PFM-LLM-008-09 source: 'services-platform:modules/llm/services/notices/threshold-notice.ts:sendThresholdNotice' coverage: partial gap: FND-PFM-LLM-067 state_transitions: - model: STATE-PFM-LLM-006 transition: 1 from: absent to: owed trigger: A settlement reaches a charged-usage threshold. gap: FND-PFM-LLM-067 provenance: proposed source: 'services-platform:modules/llm/services/metering/llm-credit-ledger.ts:evaluateCrossings' - model: STATE-PFM-LLM-006 transition: 2 from: owed to: leased trigger: A sender tries to claim the recorded crossing. gap: FND-PFM-LLM-067 provenance: proposed source: 'services-platform:modules/llm/services/persistence/allowance-periods.ts:claimThresholdNotice' - model: STATE-PFM-LLM-006 transition: 3 from: leased to: delivered trigger: At least one recipient is handled successfully or suppressed by delivery policy. gap: FND-PFM-LLM-067 provenance: proposed source: 'services-platform:modules/llm/services/persistence/allowance-periods.ts:stampThresholdNotified' - model: STATE-PFM-LLM-006 transition: 4 from: leased to: nobody_told trigger: The recipient resolver returns no eligible administrators. gap: FND-PFM-LLM-067 provenance: proposed source: 'services-platform:modules/llm/services/notices/threshold-notice.ts:sendThresholdNotice' - model: STATE-PFM-LLM-006 transition: 5 from: leased to: owed trigger: Nobody is reached or the sender stops and the lease expires. gap: FND-PFM-LLM-067 provenance: proposed source: 'services-platform:modules/llm/services/notices/retry-threshold-notices.ts:retryThresholdNotices' - model: STATE-PFM-LLM-006 transition: 6 from: leased to: given_up trigger: The last allowed claim ends without completion. gap: FND-PFM-LLM-067 provenance: proposed source: 'services-platform:modules/llm/services/persistence/allowance-periods.ts:claimThresholdNotice' - model: STATE-PFM-LLM-006 transition: 7 from: leased to: leased trigger: Delivery occurred but completion was not recorded before lease expiry. gap: FND-PFM-LLM-067 provenance: proposed source: 'services-platform:modules/llm/services/notices/threshold-notice.ts:sendThresholdNotice' domain_invariants: - invariant: INV-DOM-PFM-LLM-003-11 scenarios: - ATS-PFM-LLM-008-01 provenance: documented source: 'services-platform:modules/llm/services/metering/llm-credit-ledger.ts:evaluateCrossings' coverage_limits: finding: FND-PFM-LLM-067 statement: >- Partial delivery, lease expiry during a slow sender, post-send stamp interruption and successful delivery suppression need individual cases. The current racing-sender test covers only a live lease. provenance: proposed source: - 'services-platform:modules/llm/services/persistence/allowance-periods.ts' - 'services-platform:modules/llm/services/metering/llm-credit-ledger.ts:evaluateCrossings' - >- 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 - 'services-platform:modules/llm/services/notices/threshold-notice.ts' - 'services-platform:modules/llm/services/persistence/allowance-periods.ts' - >- services-platform:modules/llm/tests/integration/services/notices/threshold-notice.integration.spec.js#sends nothing from inside a transaction, leaving the crossing owed - 'services-platform:modules/llm/services/notices/threshold-notice.ts' - 'services-platform:modules/llm/services/notices/threshold-notice.ts' - 'services-platform:modules/llm/services/notices/threshold-notice.ts:sendThresholdNotice' invariants_without_scenarios: [] --- # undefined ## Coverage The scenarios identify the rules or journey assertions they are intended to prove. A test binding names existing evidence; an unbound proposal remains work to verify. | Scenario | Title | Level | Provenance | |---|---|---|---| | `ATS-PFM-LLM-008-01` | Threshold records remain unique under races | api | test | | `ATS-PFM-LLM-008-02` | Only charged usage crosses notice thresholds | api | proposed | | `ATS-PFM-LLM-008-03` | Only active local administrators receive notices | api | test | | `ATS-PFM-LLM-008-04` | Warning and pause messages use customer figures | api | test | | `ATS-PFM-LLM-008-05` | Competing senders claim one delivery | api | test | | `ATS-PFM-LLM-008-06` | Enclosing transactions defer notice delivery | api | test | | `ATS-PFM-LLM-008-07` | Persistent delivery failure stops after three attempts | api | test | | `ATS-PFM-LLM-008-08` | No-recipient warnings do not retry forever | api | test | | `ATS-PFM-LLM-008-09` | A retry can repeat delivery after an interrupted stamp | api | proposed | ## Interactions With Related Capabilities The interaction register links concrete experiments with admit ai work against the organization’s monthly allowance; recover interrupted requests and identify accounting drift; inspect an organization’s ai account and request history; correct an organization’s ai charges; give people understandable ai refusal messages. Each experiment checks the outcome at the shared boundary; an unbound experiment remains proposed. Partial delivery, lease expiry during a slow sender, post-send stamp interruption and successful delivery suppression need individual cases. The current racing-sender test covers only a live lease.