Rhythm 2.0 Specifications

Appearance

CAP-PFM-LLM-015Correct an organization’s AI charges

Markdown

CAP-PFM-LLM-015

Correct an organization’s AI charges

Markdown
  • DocumentDraft
  • Product intentProposed
  • ImplementationPartially observed

Planning

Feature
FEAT-PFM-LLM-05
Exercised by
FAS-PFM-LLM-05-01, FAS-PFM-LLM-05-03, FAS-PFM-LLM-05-04, FAS-PFM-LLM-05-05
Key concepts
CON-PFM-LLM-003
Actors
ACT-PFM-004, ACT-PFM-033
Depends on
CAP-PFM-LLM-007
Related
CAP-PFM-LLM-008, CAP-PFM-LLM-011
Proved by
ATS-PFM-LLM-015

Implementation

Executable suites
TST-PFM-LLM-006, TST-PFM-LLM-022, TST-PFM-LLM-070

KindCapabilityProduct areaPlatformModuleAI Requests, Usage and the Jazz AI TeammateRevision1

Read atservices-platform ad3f6a65react-console baf6dae3

Correct an organization’s AI charges ​

Purpose ​

Retain a signed correction and its reason while changing the period’s charged totals.

How It Works ​

A manager selects the period and submits a signed credit correction. Platform validates the shape, reason and any request reference. Existing months can be corrected, while a new month must be the current one. The service checks a refund against an existing charged balance. It then writes the correction, period movement and audit entry together. Returning credits is marked as widening because it can reopen admission. Duplicate submissions remain separate corrections. The product should repair the missing-period refund path and the lack of replay protection before offering the disabled console action.

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
A signed correction changes the selected period’s charged balance.The audit retains the reason and resulting figures.Correction history records signed changes even when a balance is floored at zero.
Surfaces
apiconsole
Preconditions
An existing organization is selected.
Postconditions
Correction, charged balances and audit are written atomically.
Constraints
The console correction control is incomplete.

Controls

27 controls apply, from the corpus control catalogue.

TC-AZ-001 TC-AZ-002 TC-AZ-003 TC-AZ-004 TC-AZ-005 TC-AZ-006 TC-CRY-001 TC-CRY-002 TC-CRY-003 TC-CRY-004 TC-IAM-003 TC-LOG-001 TC-LOG-002 TC-LOG-003 TC-LOG-004 TC-LOG-005 TC-MON-001 TC-PI-001 TC-PI-002 TC-PI-003 TC-PI-005 TC-TEN-001 TC-TEN-002 TC-TEN-003 TC-VEN-001 TC-VEN-002 TC-VEN-003

Permissions

KeyChecked atScope
hq.llm-usage.manageapiglobal

Business Rules

10 rules, 7 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
Only staff with the sensitive usage manage key can correct charges; support readers and customer administrators are refused without changes.
proved by ATS-PFM-LLM-015-01, TST-PFM-LLM-006
permissionapitest
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
02must prove
Proposed
Corrections require a month, a nonzero whole credit change within ten million either way and a one-to-five-hundred-character reason, accepting optional whole cents with matching sign and a request reference but no undeclared fields.
proved by ATS-PFM-LLM-015-02, ATS-PFM-LLM-015-08, TST-PFM-LLM-006, TST-PFM-LLM-022, TST-PFM-LLM-070
validationapi, serviceobserved
services-platform:modules/llm/services/adjustments/adjust-allowance.ts:requireAdjustable
03must prove
Proposed
A correction targets an existing allowance month or creates the current month; other absent periods are rejected.
proved by ATS-PFM-LLM-015-03, TST-PFM-LLM-022
validationservicetest
services-platform:modules/llm/tests/integration/services/adjustments/adjust-allowance.integration.spec.js#refuses a period the organization has no row for and that is not this month, naming the period
04must prove
Proposed
Refunds cannot exceed an existing period’s charge, but a current-month refund before any period exists bypasses that check and leaves a recorded negative correction with a zero balance.
proved by ATS-PFM-LLM-015-04, TST-PFM-LLM-022
validationserviceobserved
services-platform:modules/llm/services/adjustments/adjust-allowance.ts:requireAdjustable
05must prove
Proposed
A referenced request must belong to the organization and correction month, with foreign requests treated as absent.
proved by ATS-PFM-LLM-015-05, TST-PFM-LLM-022
validationserviceobserved
services-platform:modules/llm/services/adjustments/adjust-allowance.ts
06must prove
Proposed
The correction, period credit and money changes and audit event commit together; refunds are widening, and an audit failure rolls the correction back.
proved by ATS-PFM-LLM-007-18, ATS-PFM-LLM-008-12, ATS-PFM-LLM-011-12, ATS-PFM-LLM-015-06, TST-PFM-LLM-022
calculationservice, databaseobserved
services-platform:modules/llm/services/adjustments/adjust-allowance.ts
07
Proposed
Repeated submission creates another correction and audit event rather than replaying the first.
origin: services-platform:docs/debt/llm-adjustment-idempotency.md
policyservicedocumented
services-platform:docs/llm.md#Adjustments
08
Proposed
Correction history and the AI audit trail expose the recorded changes beside limits and capacity grants.
policyapitest
services-platform:modules/llm/tests/e2e/llm-adjustments-and-organization.e2e.spec.js#is listed by the adjustments history and by the audit read
09
Proposed
The console’s charge-correction menu item is disabled and visible only with usage management authority.
permissionconsoletest
react-console:e2e/mock/hq-ai-usage.mock.spec.ts#an administrator has the action menu, with its two writes inert
10must prove
Proposed
Applying a correction floors both period credit and cent totals at zero while retaining the signed correction amounts.
proved by ATS-PFM-LLM-015-07
calculationserviceobserved
services-platform:modules/llm/services/persistence/allowance-periods.ts:applyAllowanceAdjustment

Scenarios

IdGivenWhenThenProvenance
01A request has incurred a credit charge.An administrator applies a reasoned refund linked to it.The correction updates the period and writes its audit entry.test
services-platform:modules/llm/tests/e2e/llm-adjustments-and-organization.e2e.spec.js#writes one audit row, widening, by the staff member, of this tenant

Edge Cases

IdGivenWhenThenProvenance
02A correction links a request from another period.The service validates the correction.It refuses the mismatch and leaves period balances unchanged.test
services-platform:modules/llm/tests/e2e/llm-adjustments-and-organization.e2e.spec.js#adds up: the period still says four hundred after every refusal

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