--- id: DOM-PFM-LLM-004 title: AI Usage realises: CON-PFM-LLM-004 product_area: platform module: llm revision: 1 status: draft design_intent: proposed implementation_evidence: observed source_sha: services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f owned_by: SVC-PFM-LLM-llm readable_by: [] custom_fields: none identity: >- Daily cells are unique by organization, UTC day, application, feature, operation, provider, model, rate and outcome. A single global watermark identifies progress; other usage views are computed. attributes: - name: daily usage row kind: collection required: true computed: true notes: 'Aggregates request and attempt counts, charges, reported units and attempt latency by daily cell.' - name: rollup progress kind: date required: true computed: true notes: Tracks the boundary reached by completed rollup work. - name: reporting window kind: enum required: true computed: true notes: Selects month-to-date or a thirty- or ninety-day UTC window and its preceding comparison. - name: live position kind: computed required: true computed: true notes: 'Computes capacity, committed credits, utilisation, active grants and current status.' - name: trend and breakdown kind: computed required: true computed: true notes: 'Groups historical totals and trends, including the ten largest series and an Other remainder.' - name: request directory kind: computed required: true computed: true notes: Reads one organization’s filtered requests with newest-first pagination and capture status. - name: AI control history kind: computed required: true computed: true notes: Reads the organization’s five AI security-audit entity types in reverse chronological order. - name: organization summary kind: computed required: true computed: true notes: >- Provides credits, percentage, status, local reset, recent periods and features without staff-only detail. - name: section availability kind: enum required: true computed: true notes: Returns an available value or an unavailable result independently for each HQ section. relationships: - to: DOM-PFM-LLM-001 cardinality: many requests summarised into each daily row; one directory over an organization's requests ownership: Requests retain their source facts; this relationship does not transfer request ownership. cross_service: false - to: DOM-PFM-LLM-003 cardinality: one live position per organization from its allowance ownership: The allowance owns period accounting and configuration; linked records consume those figures. cross_service: false - to: DOM-PFM-LLM-002 cardinality: 'usage is grouped by operation, model and feature and lists the catalog' ownership: The operation catalogue owns its definitions; related records keep references. cross_service: false invariants: - id: INV-DOM-PFM-LLM-004-01 statement: >- Rebuilding replaces the organization’s entire UTC day from settled and refused requests in one transaction. enforced_at: - service - database provenance: observed source: 'services-platform:modules/llm/services/persistence/usage-rollups.ts:rebuildUsageDay' - id: INV-DOM-PFM-LLM-004-02 statement: Daily reporting uses request start day and excludes work still running. enforced_at: - service provenance: documented source: 'services-platform:docs/llm.md#The daily rollup' - id: INV-DOM-PFM-LLM-004-03 statement: The watermark advances monotonically behind the run start and stops at unfinished changes. enforced_at: - service - database provenance: observed source: >- services-platform:modules/llm/services/reconciliation/rollup-settled-invocations.ts:rollUpSettledInvocations - id: INV-DOM-PFM-LLM-004-04 statement: >- The documented HQ reporting reader accesses daily aggregates without access to raw requests, tasks or attempts. enforced_at: - database provenance: documented source: 'services-platform:docs/llm.md#Reporting' - id: INV-DOM-PFM-LLM-004-05 statement: Usage responses expose capture state without bodies or object-storage references. enforced_at: - api provenance: observed source: 'services-platform:modules/llm/aws/api/llm-usage-api-mapper.ts:toInvocationDetailResponse' - id: INV-DOM-PFM-LLM-004-06 statement: Customer summaries contain credits and percentages while excluding prices and internal capacity details. enforced_at: - api - service provenance: observed source: 'services-platform:modules/llm/aws/api/llm-usage-api-mapper.ts:toOrganizationSummaryResponse' - id: INV-DOM-PFM-LLM-004-07 statement: A failed section read returns unavailable independently of neighbouring sections. enforced_at: - service provenance: observed source: 'services-platform:modules/llm/services/usage-reports/section.ts:readSection' - id: INV-DOM-PFM-LLM-004-08 statement: >- Current switches and committed-credit figures determine status; crossings do not override available live data. enforced_at: - service provenance: observed source: 'services-platform:modules/llm/services/usage-reports/usage-status.ts:deriveUsageStatus' physical: - platform.llm_usage_daily - platform.llm_rollup_watermarks - platform.llm_usage_daily_query (reporting view) - platform.llm_invocations_query (reporting view) evidence: - >- services-platform at ad3f6a6: modules/llm/db/llm-usage-daily.table.ts, llm-rollup-watermarks.table.ts, llm-usage-daily-query.view.ts, llm-invocations-query.view.ts; services/persistence/usage-rollups.ts; services/reconciliation/rollup-settled-invocations.ts; services/usage-reports/*; services/usage/*; aws/api/llm-usage-api-mapper.ts; db/row-level-security.ts; docs/llm.md (The daily rollup, The HQ surface, Reporting). - 'react-console at baf6dae: components/console/hq/ai-usage/**; lib/hq/ai-usage.ts.' --- # AI Usage ## What It Models AI usage combines historical cost reporting, live allowance status and request inspection. These views have different freshness: daily totals follow reconciliation, current capacity is read directly, and request details describe individual attempts and settlement. ## Identity and Attributes Stored daily cells are unique for an organization, UTC day and reporting dimensions, including outcome and rate version. A global watermark tracks rollup progress. Other views calculate windows, comparisons, status, request lists and audit history as they are read. ## Relationships Request history supplies daily totals. Allowance records supply current capacity and status. Catalogue declarations supply feature and operation labels. Security owns control audit storage, while Queries owns datasets and reusable reports over the supplied views. ## Invariants Rebuilding replaces an entire organization-day within a transaction. Progress advances conservatively and stops at unfinished changes. Usage responses exclude evidence bodies and storage keys. Customer answers also exclude internal monetary and control details. Independent HQ sections can answer unavailable without failing their neighbours. ## How It Is Stored and Shared The reconciliation function writes daily aggregates and their watermark. The aggregate has a documented row-policy exemption for cross-organization reporting. HQ APIs use it for history and enter organizations for live detail. Customer APIs and query datasets provide scoped projections without transferring record ownership to the console. ## Open Design Questions UTC reporting windows differ from local allowance months. Early-warning signals, raw-record retention and the provider circuit breaker remain incomplete. An unreadable organization prevents global watermark advancement, even while other days are rebuilt. The customer dashboard has no implemented page.