---
id: WF-PFM-LLM-006
title: Rebuild the daily usage rollup
trigger: Recompute affected daily reporting cells.
product_area: platform
module: llm
revision: 1
status: draft
design_intent: proposed
implementation_evidence: observed
inference: []
source_sha:
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
implements:
  - CAP-PFM-LLM-010
crosses:
  - SVC-PFM-LLM-llm
idempotency: >-
  Replace a complete organization-day inside a transaction, preserving equivalent totals on repetition.
  Progress never advances beyond an unfinished boundary.
concurrency: >-
  Single deployed reconciliation concurrency prevents overlapping scheduled rebuilds. The five-minute margin
  is a conservative assumption about commit timing, not a transaction fence.
hops:
  - 'n': 1
    actor_or_service: Rollup step
    action: Read the watermark and choose a bound five minutes before run start.
    anchor: 'services-platform:modules/llm/services/persistence/usage-rollups.ts:getRollupWatermark'
    seam: sync
    on_failure: Log a step failure and retain prior progress.
    left_inconsistent: Reporting freshness declines.
    observer: 'Rollup logs, daily totals, progress and lag metrics.'
    provenance: observed
    source: >-
      services-platform:modules/llm/services/reconciliation/rollup-settled-invocations.ts:rollUpSettledInvocations
  - 'n': 2
    actor_or_service: Rollup step (in each operational organization)
    action: Discover changed UTC days across operational organizations.
    anchor: 'services-platform:modules/llm/services/persistence/usage-rollups.ts:listChangedUsageDates'
    seam: sync
    on_failure: Record unreadable organizations and continue collecting others.
    left_inconsistent: Any unreadable organization blocks global progress for this run.
    observer: 'Rollup logs, daily totals, progress and lag metrics.'
    provenance: observed
    source: >-
      services-platform:modules/llm/services/reconciliation/rollup-settled-invocations.ts:rollUpSettledInvocations
  - 'n': 3
    actor_or_service: Rollup step (in the organization)
    action: >-
      Replace each affected organization-day with aggregates of settled and refused requests and their
      attempts.
    anchor: 'services-platform:modules/llm/services/persistence/usage-rollups.ts:rebuildUsageDay'
    seam: sync
    on_failure: Roll back that day on failure and continue other discovered days.
    left_inconsistent: The failed day retains its previous totals until a later rebuild.
    observer: 'Rollup logs, daily totals, progress and lag metrics.'
    provenance: observed
    source: 'services-platform:modules/llm/services/persistence/usage-rollups.ts:rebuildUsageDay'
  - 'n': 4
    actor_or_service: Rollup step
    action: Stop rebuilds when the budget is spent and advance progress only to a safe completed boundary.
    anchor: 'services-platform:modules/llm/services/persistence/usage-rollups.ts:advanceRollupWatermark'
    seam: sync
    on_failure: Retain previous progress if the watermark write fails.
    left_inconsistent: A later run repeats already completed rebuilds.
    observer: 'Rollup logs, daily totals, progress and lag metrics.'
    provenance: observed
    source: >-
      services-platform:modules/llm/services/reconciliation/rollup-settled-invocations.ts:LLM_ROLLUP_TIME_BUDGET_MS
branches: []
waits:
  - Rebuild processing checks a two-minute budget between days.
evidence:
  - >-
    services-platform at ad3f6a6: modules/llm/services/reconciliation/rollup-settled-invocations.ts;
    services/persistence/usage-rollups.ts; db/llm-usage-daily.table.ts, llm-rollup-watermarks.table.ts;
    aws/logic/llm-reconciliation.lambda.ts (LlmRollupLagAlarm); db/row-level-security.ts; docs/llm.md#The
    daily rollup.
controls: [TC-AVL-001, TC-AVL-005, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-005, TC-CHG-001, TC-CHG-002, TC-CHG-003, TC-CHG-004, TC-CHG-005, TC-CHG-006, TC-IAM-001, TC-IAM-002, TC-IAM-003, TC-IAM-004, TC-IAM-005, TC-IAM-006, 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]
---

# Rebuild the daily usage rollup

## What It Does

Hourly reconciliation derives history from settled and refused requests rather than incrementing totals in the request path.

## The Flow

```mermaid
flowchart TD
  H1["Read the watermark and choose a bound five minutes before run start."]
  H2["Discover changed UTC days across operational organizations."]
  H1 --> H2
  H3["Replace each affected organization-day with aggregates of settled and refused requests and their attempts."]
  H2 --> H3
  H4["Stop rebuilds when the budget is spent and advance progress only to a safe completed boundary."]
  H3 --> H4
```

Discover changed days since the watermark, rebuild oldest changes first, and advance only through a safe boundary five minutes behind start.

## When Something Fails

Failed organization discovery blocks global progress. Failed days retain prior cells and bound progress; completed days can be repeated harmlessly. A first blocked run with no watermark reports zero lag.

## Open Design Questions

The UTC reporting-day assumption and global-progress blockage need explicit acceptance.