# Forecast-to-actual resource control

## Why the €2.89, €5.14, €62.89, and €65.14 figures differ

They describe two volumes and two cost scopes:

| Figure | Stored volume | Scope | Calculation |
| --- | ---: | --- | --- |
| €2.89 | 180 GB | infrastructure only | 180 × €0.01606 |
| €62.89 | 180 GB | infrastructure + internal labor | €2.89 + 1 h × €60 |
| €5.14 | 320 GB | infrastructure only | 320 × €0.01606 |
| €65.14 | 320 GB | infrastructure + internal labor | €5.14 + 1 h × €60 |

The older €62.89 estimate was not “storage without elastic cost”; it already
included the €60 monthly operator allowance. The normalized table introduced a
different stored volume and showed infrastructure separately. Future reports
must always label both `stored_gb` and cost scope.

## Control records

A forecast is a timestamped, immutable record of what was believed at decision
time. The initial base forecast is
`data/forecasts/platform-audit-storage-scaleway-base-2026-08.json`. Do not edit
it after actual evidence exists. If assumptions change, create a new forecast
with a new creation date and retain the prior one so forecast accuracy remains
auditable.

After every billing month, record a technical `usage_observation` under
`data/actuals/`. Authoritative booked financial facts come from fin-hub and
are joined by reference; resource-control does not originate a second booked
actual.
The required cost and usage proxies are:

- database size and provider stored bytes;
- WAL volume;
- write and read requests;
- restore-test egress;
- infrastructure invoice cost;
- internal operations hours and valued labor cost;
- total attributable cost;
- backup success, maximum observed RPO, and restore RTO when measured.

Provider stored bytes are intentionally distinct from logical database size.
They expose base-backup retention, WAL, compression, versioning, incomplete
multipart uploads, and lifecycle behavior. Invoice cost is distinct from the
provider's usage estimator and must reconcile to non-secret billing evidence.

## Error calculation and review

`make variance ACTUAL=data/actuals/YYYY-MM.json` reports signed error and
absolute percentage error for each numeric proxy. Initially review rather than
automatically rewrite assumptions:

- investigate infrastructure cost error above 10%;
- investigate stored-byte or WAL error above 20%;
- investigate any unplanned egress or request-class charge;
- investigate labor error above 1 hour or 25%;
- investigate every backup failure, RPO breach, or restore-RTO regression.

After three comparable months, calculate mean absolute percentage error by
proxy and recalibrate the next forecast. Avoid MAPE where the forecast is zero;
use absolute error and explain the new activity instead. Separate forecast
error from price variance: a bill can differ because usage was wrong, the rate
changed, tax/discount treatment differed, or an unmodeled SKU appeared.

Quarterly provider comparison should use the latest actual trailing three
months, the next 12-month forecast, one monthly restore, an exit event, and
observed—not aspirational—operator labor.

## General portfolio control record

The storage-specific v0.1 observation remains valid for the backup procurement
case. New portfolio controls use
`schemas/resource-control-cycle.schema.json`, whose resource-specific
`usage_proxies` allow the same comparison mechanism to cover storage, VMs or
cluster compute, shared platform services, managed services, and future
resource types without pretending they share the same utilization unit.

Each record separates:

- provisioned and used capacity, with a fixed, elastic, or hybrid model;
- infrastructure, internal labor, and external labor cost;
- booked financial facts, referenced rather than copied from fin-hub;
- allocation method, driver, version, and unattributed residual;
- service constraints and their units;
- low/base/high forecast scenario or observed actual;
- evidence and uncertainty.

Forecast records are append-only. A changed forecast receives a new
`record_id`, creation time, and `revision_of` reference. Actuals must name the
exact original `forecast_ref`; a later revision must never replace the
decision-time baseline when measuring forecast error.

Run a generic comparison with:

```sh
make control-cycle FORECAST=examples/control-cycle/storage-forecast.json \
  ACTUAL=examples/control-cycle/storage-actual.json
```

The examples cover storage, `reef-railiance` cluster compute, and the shared
`apps-pg` service. Their numbers are illustrative contract fixtures, not booked
facts. Operational records replace their evidence references after the owner
workplans publish observations.

## Variance attribution

Every material variance is assigned to one of six controlled categories:

- `demand`: the amount of consumed service differed;
- `provider_price`: rate, discount, tax, currency, or billed SKU differed;
- `allocation`: a shared-cost driver or attribution changed;
- `labor`: internal or external effort differed;
- `model`: a formula, assumption, capacity behavior, or omitted component was
  wrong;
- `data_quality`: evidence is missing, late, inconsistent, or uses a different
  unit.

The comparator defaults usage differences to demand, infrastructure cost to
provider price, and labor fields to labor, while preserving explicit
attribution supplied with the actual. Missing proxies and unit mismatches fail
closed as data-quality errors. Attribution explains an error; it does not
rewrite the forecast.