resource-control/docs/portfolio-operating-cadence.md

Portfolio reporting and operating cadence

make portfolio-report renders the current portfolio view from tools/portfolio_report.py. The report is derived entirely from committed evidence: resource records in data/resources/, the latest data/portfolio-coverage-*.json, and the optimization cases in data/optimization/. Nothing in it is typed by hand.

What the report answers

Section	Question
coverage	Which service groups are represented, and which evidence gaps are still delegated and to whom.
lifecycle	How many resources sit in each lifecycle state, and whether any lacks an owner.
utilization	Provisioned versus observed capacity per metric, flagged idle, normal, or saturated; and which resources cannot be measured at all.
cost	Which resources carry price evidence, which do not, and which have no allocation method so their cost reaches no consumer.
renewals	Contract dates inside the 90-day horizon, and resources with no recorded dates at all.
risks	Concentrated failure domains, unpriced resources, unattributed cost, idle and saturated capacity.
optimization	Open cases, their per-option verdicts, and the named evidence blocking each one.
next_actions	The smallest set of evidence that would unblock the most decisions, addressed to the repository that owns it.

Not forcing false precision

Two rules the report holds to, because the alternative is a number that looks authoritative and is not:

• known_monthly_spend_eur is null, not 0. No booked cost has reached this repository, and six of seven resources carry no price evidence. Summing what happens to be known would report a portfolio spend an order of magnitude below reality. The figure stays unknown until fin-hub delivers booked facts under docs/fin-hub-resource-control-contract-v0.1.md.
• Unattributed cost is a list, not a spread. Four resources have allocation mode unattributed. Their cost is not divided across consumers by a plausible default; they are named, and the allocation driver is owed by the repository that owns the resource.

Resources that cannot be measured appear in utilization.unmeasured with the reason, rather than being silently omitted from the ratios.

Cadence

Rhythm	When	Inputs	Consumers	Output
Monthly observation	First week, for the closed month	Monthly actual records from delegated telemetry; booked costs from fin-hub	resource-control	tools/control_cycle.py variance per resource; a new optimization case where variance is attributed to demand, price, or allocation rather than data quality
Monthly settlement	With the observation, once entity association is live	Per-entity usage, delivered cost, transfer prices under docs/TermsOfResourceProcurement.md; recognized payments from fin-hub	consuming financial entities; Railiance operations; fin-hub	One settlement statement and credit-state evaluation (open or restricted) per consuming entity
Monthly portfolio report	With the observation	Resource records, coverage, optimization cases	Human operator; owning repositories	make portfolio-report; the next_actions list is re-sent to the repositories named in it
Quarterly calibration	End of quarter	Three months of variance	resource-control; fin-hub	Forecast revisions per docs/forecast-actual-control.md — revisions, never overwrites; refreshed provider prices in every open case
Pre-renewal review	At least 60 days before the earliest renews_on or cancel_by	Contract evidence, utilization, open cases	Human financial authority	A renewal case, decided while cancellation is still possible
Event-driven	Sustained variance beyond threshold, an incident exposing a failure domain, or a workload request	The triggering evidence	Owning repository	A case of the matching type per docs/optimization-cases.md

Delivered evidence stays visible

A delegated gap that is answered does not vanish from the report. It moves from coverage.unresolved_gaps to coverage.delivered_gaps, keeping the interface that answered it and the residual unknowns it did not, and each residual still generates a next action. Partial delivery must not read as full coverage.

RAILIANCE-WP-0016 is the first example: railiance-platform delivered apps-pg capacity, utilization, consumers, and the apps-pg-dbbytes-v1 allocation driver, and deliberately delivered no EUR. Three residuals remain open — the booked host share, the labour estimate, and the absent recovery objectives — so apps-pg is now measurable and attributed while still counting as unpriced.

Reading the current report

As of 2026-08-14 an operator asking the four questions this cadence exists to answer gets these answers, and the honest ones are the useful ones:

• Material spend? Unknown, and explicitly so. Only the proposed backup storage carries price evidence. Every other resource is waiting on RAIL-HO-WP-0008 and FIN-WP-0004.
• Idle or saturated capacity? railiance01, the reef-railiance k3s cluster, and apps-pg are idle on every measured metric — 14 percent CPU, 37 percent memory, and 5.8 percent of the apps-pg volume. Nothing is saturated. Four resources cannot be measured at all.
• Forecast error? Not yet computable. The first operational forecast record exists for apps-pg, but its period is 2026-09 and no actual has been observed against it, so there is no variance to report and none is fabricated. Its infrastructure cost is null, so even when the actual lands, cost variance will read unknown until a booked fact arrives.
• Approaching commitments? None visible — and that is itself the finding: six active resources have no renewal or cancellation date recorded, so the cancellation window cannot be respected for any of them.
• Next evidence-backed action? The next_actions list, led by the seven delegated workplans that own the missing evidence.

The single largest structural risk the report surfaces is concentration: six of seven resources share host:railiance01, including the backup storage's own intended protection target. That is the standing argument for placing backup storage outside the Host Europe failure domain, and it is visible in the report rather than only in prose.