Story-2541 — S3 Storage Allocation & Monthly AWS Reconciliation

pramaan-functions · RFD-BILL-002 §6.4 + §8 · Epic-2469 Phase 3 · (the governing Story exempts walkthrough delivery; this page exists for the closes-check gate and as the reconciliation report's shape reference)

1. What ships

One scheduled worker, src/workers/storage_allocation/handler.lambda_handler, with two modes. Daily: one ListObjectsV2 sweep of the document bucket, bytes grouped by firms/<uuid>/ prefix and storage class, one allocation-estimate event per firm/day/class in billing.vendor_cost_event: quantity = bytes x 24 byte-hours, cost = byte-hours x the settings-data rate (S3_STORAGE_RATE_USD_MICROS_PER_GB_MONTH), integer USD micros. Reconcile (auto on the month's first run, or explicit): prior month's allocated total vs the Cost Explorer S3 capacity total (TimedStorage-*), variance distributed pro-rata as linked adjustment events.

2. The invariants

Idempotency storage:<firm>:<date>:<class> — every re-drive/backfill dedupes to zero new rows; the ledger's unique key + CHECK grammar enforce it in Postgres, not just in code.

Unknown prefixes are QUARANTINED: an unattributed event with firm_id = NULL (staff-visible platform overhead) plus an error-level storage_allocation_unattributed_keys log. Never silently assigned to a firm.

Reconciliation appends; history is never edited. Each adjustment links to that firm bucket's latest estimate of the month via reconciles_event_id (storage:reconcile:<month>:<firm>).

Storage cost stays internal: writes go only to the platform-private ledger (staff-only RLS read). No customer route, no customer storage charge.

3. Where things live

Piece	Path
Pure allocation math + shares	`src/domains/vendor_cost_event/storage_allocation.py`
Worker handler (scan, CE fetch, writes)	`src/workers/storage_allocation/handler.py`
Rates as data + variance threshold	`src/shared/settings.py` (`S3_STORAGE_RATE_*`, `S3_RECONCILE_VARIANCE_ALERT_PCT`)
Invocation contract for Chore-2549	`docs/notes/storage-allocation-worker-contract.md`
Unit proof (math, quarantine, determinism, linkage)	`tests/unit/test_storage_allocation.py`, `tests/unit/test_storage_allocation_handler.py`

4. The reconciliation report (proof artifact)

{
  "ok": true, "mode": "reconcile", "month": "2026-06",
  "aws_total_usd_micros": 1100, "allocated_total_usd_micros": 1000,
  "variance_usd_micros": 100,
  "adjustments_created": 3, "adjustments_deduped": 0
}

Emitted as the structured storage_reconcile_completed log per run; variance beyond S3_RECONCILE_VARIANCE_ALERT_PCT raises an error-level alert log.