--- id: CAP-PFM-LLM-015 title: Correct an organization’s AI charges feature: FEAT-PFM-LLM-05 product_area: platform module: llm revision: 1 status: draft product_intent: proposed implementation_evidence: partially-observed supersedes: [] source_sha: services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f intent_sources: [] purpose: Retain a signed correction and its reason while changing the period’s charged totals. 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. concepts: - CON-PFM-LLM-003 actors: - ACT-PFM-004 - ACT-PFM-033 surfaces: - api - console preconditions: - An existing organization is selected. postconditions: - 'Correction, charged balances and audit are written atomically.' permissions: - key: hq.llm-usage.manage where_checked: api scope: global rules: - id: BR-CAP-PFM-LLM-015-01 proved_by: [ATS-PFM-LLM-015-01, TST-PFM-LLM-006] statement: >- Only staff with the sensitive usage manage key can correct charges; support readers and customer administrators are refused without changes. kind: permission enforced_at: - api must_prove: true provenance: test 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 origin: none - id: BR-CAP-PFM-LLM-015-02 proved_by: [ATS-PFM-LLM-015-02, ATS-PFM-LLM-015-08, TST-PFM-LLM-006, TST-PFM-LLM-022, TST-PFM-LLM-070] statement: >- 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. kind: validation enforced_at: - api - service must_prove: true provenance: observed source: 'services-platform:modules/llm/services/adjustments/adjust-allowance.ts:requireAdjustable' origin: none - id: BR-CAP-PFM-LLM-015-03 proved_by: [ATS-PFM-LLM-015-03, TST-PFM-LLM-022] statement: >- A correction targets an existing allowance month or creates the current month; other absent periods are rejected. kind: validation enforced_at: - service must_prove: true provenance: test source: >- 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 origin: none - id: BR-CAP-PFM-LLM-015-04 proved_by: [ATS-PFM-LLM-015-04, TST-PFM-LLM-022] statement: >- 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. kind: validation enforced_at: - service must_prove: true provenance: observed source: 'services-platform:modules/llm/services/adjustments/adjust-allowance.ts:requireAdjustable' origin: none - id: BR-CAP-PFM-LLM-015-05 proved_by: [ATS-PFM-LLM-015-05, TST-PFM-LLM-022] statement: >- A referenced request must belong to the organization and correction month, with foreign requests treated as absent. kind: validation enforced_at: - service must_prove: true provenance: observed source: 'services-platform:modules/llm/services/adjustments/adjust-allowance.ts' origin: none - id: BR-CAP-PFM-LLM-015-06 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] statement: >- The correction, period credit and money changes and audit event commit together; refunds are widening, and an audit failure rolls the correction back. kind: calculation enforced_at: - service - database must_prove: true provenance: observed source: 'services-platform:modules/llm/services/adjustments/adjust-allowance.ts' origin: none - id: BR-CAP-PFM-LLM-015-07 proved_by: [] statement: Repeated submission creates another correction and audit event rather than replaying the first. kind: policy enforced_at: - service must_prove: false provenance: documented source: 'services-platform:docs/llm.md#Adjustments' origin: 'services-platform:docs/debt/llm-adjustment-idempotency.md' - id: BR-CAP-PFM-LLM-015-08 proved_by: [] statement: Correction history and the AI audit trail expose the recorded changes beside limits and capacity grants. kind: policy enforced_at: - api must_prove: false provenance: test source: >- services-platform:modules/llm/tests/e2e/llm-adjustments-and-organization.e2e.spec.js#is listed by the adjustments history and by the audit read origin: none - id: BR-CAP-PFM-LLM-015-09 proved_by: [] statement: The console’s charge-correction menu item is disabled and visible only with usage management authority. kind: permission enforced_at: - console must_prove: false provenance: test source: >- react-console:e2e/mock/hq-ai-usage.mock.spec.ts#an administrator has the action menu, with its two writes inert origin: none - id: BR-CAP-PFM-LLM-015-10 proved_by: [ATS-PFM-LLM-015-07] statement: >- Applying a correction floors both period credit and cent totals at zero while retaining the signed correction amounts. kind: calculation enforced_at: - service must_prove: true provenance: observed source: 'services-platform:modules/llm/services/persistence/allowance-periods.ts:applyAllowanceAdjustment' origin: none scenarios: - id: SC-CAP-PFM-LLM-015-01 given: A request has incurred a credit charge. when: An administrator applies a reasoned refund linked to it. then: The correction updates the period and writes its audit entry. provenance: test source: >- 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: - id: SC-CAP-PFM-LLM-015-02 given: A correction links a request from another period. when: The service validates the correction. then: It refuses the mismatch and leaves period balances unchanged. provenance: test source: >- services-platform:modules/llm/tests/e2e/llm-adjustments-and-organization.e2e.spec.js#adds up: the period still says four hundred after every refusal constraints: - The console correction control is incomplete. depends_on: - CAP-PFM-LLM-007 related: - CAP-PFM-LLM-008 - CAP-PFM-LLM-011 journeys: [] open_questions: [] evidence: - >- services-platform at ad3f6a6582843008ed0f5a17b131878d15829af1: docs/llm.md (Adjustments); docs/debt/llm-adjustment-idempotency.md; docs/milestones/PLAT-M2-ai-usage-hq-controls.md; aws/api/llm-usage.routes.ts (createHqTenantLlmUsageAdjustment); aws/api/llm-usage.schemas.ts; services/adjustments/adjust-allowance.ts; services/persistence/allowance-periods.ts; db/llm-allowance-adjustments.table.ts; tests e2e/llm-adjustments-and-organization.e2e.spec.js, integration/services/adjustments/adjust-allowance.integration.spec.js, unit/services/adjustments/adjustment-request.spec.ts. - >- react-console at baf6dae382d6f41dce976c7f848667ccc37e076f: components/console/hq/tenant-ai-usage-card.tsx; e2e/mock/hq-ai-usage.mock.spec.ts. controls: [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] exercised_by: [FAS-PFM-LLM-05-01, FAS-PFM-LLM-05-03, FAS-PFM-LLM-05-04, FAS-PFM-LLM-05-05] suites: [TST-PFM-LLM-006, TST-PFM-LLM-022, TST-PFM-LLM-070] --- # 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.