---
id: WF-PFM-LLM-012
title: Assemble usage across organizations
trigger: Assemble HQ historical totals and live organization positions.
product_area: platform
module: llm
revision: 1
status: draft
design_intent: proposed
implementation_evidence: observed
inference: []
source_sha:
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
  react-console: baf6dae382d6f41dce976c7f848667ccc37e076f
implements:
  - CAP-PFM-LLM-010
  - CAP-PFM-LLM-005
crosses:
  - SVC-PFM-LLM-llm
idempotency: Reporting performs reads without a module write.
concurrency: >-
  Organization position and leader collection use bounded parallelism. Independent report requests can observe
  different instants and should not be treated as one snapshot.
hops:
  - 'n': 1
    actor_or_service: Rhythm HQ console
    action: Request HQ reporting sections with the usage-read authority.
    anchor: 'react-console:lib/hq/ai-usage.ts:createLiveHqAiUsageApi'
    seam: sync
    on_failure: Show failure for each failed section independently.
    left_inconsistent: No report write occurs.
    observer: Independent HQ section state and API logs.
    provenance: observed
    source: 'react-console:components/console/hq/ai-usage/ai-usage-dashboard.tsx:AiUsageDashboard'
  - 'n': 2
    actor_or_service: LLM usage API (platform-wide reads)
    action: Read rollup history for the selected UTC reporting window and comparison.
    anchor: 'services-platform:modules/llm/services/persistence/usage-rollups.ts:readRollupTotals'
    seam: sync
    on_failure: Answer unavailable for the failed section.
    left_inconsistent: Other reporting sections can still be read.
    observer: Independent HQ section state and API logs.
    provenance: observed
    source: 'services-platform:modules/llm/services/usage-reports/platform-usage.ts:getPlatformSummary'
  - 'n': 3
    actor_or_service: LLM usage API (per-organization positions)
    action: Enter organizations in bounded parallel groups to calculate their live allowance positions.
    anchor: 'services-platform:modules/llm/services/usage-reports/tenant-positions.ts:readTenantUsagePositions'
    seam: sync
    on_failure: Log unreadable organizations and omit their live figures.
    left_inconsistent: A historical row can be returned without current position data.
    observer: Independent HQ section state and API logs.
    provenance: observed
    source: 'services-platform:modules/llm/services/usage-reports/tenant-positions.ts:forEachConcurrently'
  - 'n': 4
    actor_or_service: LLM usage API (costliest tasks)
    action: Collect high-cost closed tasks across organizations and report unreadable organizations separately.
    anchor: 'services-platform:modules/llm/services/usage-reports/execution-leaders.ts:collectLeadersAcrossTenants'
    seam: sync
    on_failure: Continue after individual organization-read failure.
    left_inconsistent: The returned leaders can exclude tasks from unreadable organizations.
    observer: Independent HQ section state and API logs.
    provenance: observed
    source: 'services-platform:modules/llm/services/usage-reports/executions.ts:listPlatformExecutions'
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;
    services/usage-reports/platform-usage.ts, tenant-positions.ts, executions.ts, execution-leaders.ts,
    section.ts, usage-windows.ts, usage-status.ts; services/persistence/usage-rollups.ts; docs/llm.md#The HQ
    surface.
  - 'react-console at baf6dae: lib/hq/ai-usage.ts; components/console/hq/ai-usage/*.'
controls: [TC-AI-001, TC-AI-002, TC-AI-003, TC-AI-004, TC-AI-006, TC-AI-007, TC-AVL-001, TC-AVL-005, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-005, TC-AZ-006, TC-CHG-001, TC-CHG-002, TC-CHG-003, TC-CHG-004, TC-CHG-005, TC-CHG-006, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-DAT-004, 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-MON-002, 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]
---

# Assemble usage across organizations

## What It Does

HQ history uses the derived daily table, while current allowance and task reads enter organizations with bounded concurrency.

## The Flow

```mermaid
flowchart TD
  H1["Request HQ reporting sections with the usage-read authority."]
  H2["Read rollup history for the selected UTC reporting window and comparison."]
  H1 --> H2
  H3["Enter organizations in bounded parallel groups to calculate their live allowance positions."]
  H2 --> H3
  H4["Collect high-cost closed tasks across organizations and report unreadable organizations separately."]
  H3 --> H4
```

Request separate report sections, read rollup totals and resolve selected live positions and execution leaders.

## When Something Fails

A failed section returns unavailable. Failed organization entry omits its live position or names it as unreadable without turning missing data into zero.

## Open Design Questions

Client-side search filters loaded organizations; early-warning signals remain unavailable.