---
id: WF-PFM-LLM-007
title: Change an organization's AI limits
trigger: Replace an organization’s recurring AI controls.
product_area: platform
module: llm
revision: 1
status: draft
design_intent: proposed
implementation_evidence: partially-observed
inference: []
source_sha:
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
  react-console: baf6dae382d6f41dce976c7f848667ccc37e076f
implements:
  - CAP-PFM-LLM-013
moves:
  - STATE-PFM-LLM-005
crosses:
  - SVC-PFM-LLM-llm
idempotency: >-
  Identical existing limits return unchanged without another audit despite a stale supplied version. Different
  values require the inspected version.
concurrency: >-
  Existing configuration is locked and versioned; absent-row insert races use conflict refusal. The
  current-month synchronization and audit commit with changed limits.
hops:
  - 'n': 1
    actor_or_service: Rhythm HQ console
    action: Display configured and default limits; keep the manager’s Edit Limits action disabled.
    anchor: 'react-console:components/console/hq/tenant-ai-usage-card.tsx:AiUsageMenu'
    seam: sync
    on_failure: There is no implemented screen save to fail.
    left_inconsistent: No screen mutation occurs.
    observer: API response and security audit history for committed control changes.
    provenance: observed
    source: 'react-console:components/console/hq/tenant-ai-usage-card.tsx:AiUsageMenu'
  - 'n': 2
    actor_or_service: LLM usage API
    action: Authorize preview or save through the management route and require inspected version on save.
    anchor: 'services-platform:modules/llm/aws/api/llm-usage.routes.ts:putHqTenantLlmUsageLimits'
    seam: sync
    on_failure: 'Reject unauthorized, malformed, unversioned or missing-organization requests.'
    left_inconsistent: No accepted write occurs.
    observer: API response and security audit history for committed control changes.
    provenance: observed
    source: 'services-platform:modules/llm/aws/api/llm-usage-api-mapper.ts:mapLimitsWriteRequest'
  - 'n': 3
    actor_or_service: Limits service
    action: 'Validate allowance, cap, declared disabled keys, notes and required reason.'
    anchor: 'services-platform:modules/llm/services/limits/tenant-limits.ts:validateTenantLimitsInput'
    seam: sync
    on_failure: Return field validation errors before persistence.
    left_inconsistent: 'No limits, month or audit change occurs.'
    observer: API response and security audit history for committed control changes.
    provenance: observed
    source: 'services-platform:modules/llm/services/limits/tenant-limits.ts:validateLimitsReason'
  - 'n': 4
    actor_or_service: Limits service (preview)
    action: Calculate a proposed monthly position and ceiling pressure without saving.
    anchor: 'services-platform:modules/llm/services/limits/tenant-limits.ts:previewTenantLimitsFor'
    seam: sync
    on_failure: Return read errors without writing.
    left_inconsistent: No persistent preview effect exists.
    observer: API response and security audit history for committed control changes.
    provenance: observed
    source: 'services-platform:modules/llm/services/limits/tenant-limits.ts:previewTenantLimitsFor'
  - 'n': 5
    actor_or_service: Limits service (save)
    action: 'Write changed limits, synchronize the current base and append the audit in one transaction.'
    anchor: 'services-platform:modules/llm/services/limits/tenant-limits.ts:upsertTenantLimits'
    seam: sync
    on_failure: Reject stale changed values or roll back all writes on failure.
    left_inconsistent: An unchanged replay preserves existing values without another audit.
    observer: API response and security audit history for committed control changes.
    provenance: observed
    source: 'services-platform:modules/llm/services/persistence/allowance-periods.ts:syncAllowancePeriodToLimits'
branches:
  - The structured hops retain the applicable alternative path and its failure boundary.
waits: []
evidence:
  - >-
    services-platform at ad3f6a6: modules/llm/aws/api/llm-usage.routes.ts, llm-usage-api-mapper.ts;
    services/limits/tenant-limits.ts; services/persistence/limits.ts, allowance-periods.ts;
    modules/security/services/persistence/audit-events.ts (recordSecurityAuditEvent, read to name it);
    tests/e2e/llm-limits.e2e.spec.js; docs/llm.md#Limits.
  - 'react-console at baf6dae: components/console/hq/tenant-ai-usage-card.tsx.'
controls: [TC-AVL-005, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-005, TC-IAM-001, TC-IAM-002, TC-IAM-003, TC-IAM-004, TC-IAM-005, 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]
---

# Change an organization's AI limits

## What It Does

The implemented service accepts a management-authorized preview or full replacement, while the console save remains disabled.

## The Flow

```mermaid
flowchart TD
  H1["Display configured and default limits; keep the manager’s Edit Limits action disabled."]
  H2["Authorize preview or save through the management route and require inspected version on save."]
  H1 --> H2
  H3["Validate allowance, cap, declared disabled keys, notes and required reason."]
  H2 --> H3
  H4["Calculate a proposed monthly position and ceiling pressure without saving."]
  H3 --> H4
  H5["Write changed limits, synchronize the current base and append the audit in one transaction."]
  H4 --> H5
```

Validate values, preview without writing, or commit changed configuration, current-month base and security audit together.

## When Something Fails

Changed stale versions are rejected. A replay matching existing values returns unchanged, while two first writers can conflict even with identical values.

## Open Design Questions

Enabling the screen requires its missing save flow; this contract does not approve a new policy.