resource-control/workplans/RESOURCE-WP-0003-managed-infrastructure-portfolio-control.md

---
id: RESOURCE-WP-0003
type: workplan
title: "Establish managed-infrastructure portfolio control"
domain: financials
repo: resource-control
status: finished
owner: codex
topic_slug: railiance
created: "2026-08-10"
updated: "2026-08-14"
related:
  - RESOURCE-WP-0002
  - FIN-WP-0004
state_hub_workstream_id: "b4d541d2-c114-4189-b431-e301c4dcef4e"
---

# RESOURCE-WP-0003 — managed-infrastructure portfolio control

## Goal

Turn the revised repository intent into an operational, provider-neutral
control loop for infrastructure serving Railiance itself, Helix Forge, Coulomb
Social, shared platform services, and tenant workloads. Establish the portfolio
model, authority contracts, delegated evidence interfaces, and a repeatable
forecast-to-actual optimization cycle without duplicating financial, workload,
or platform authority.

The PostgreSQL backup work in `RESOURCE-WP-0002` is the first proving case and
input to this workplan, not the limit of its scope.

## Boundaries

- `resource-control` owns portfolio identity, lifecycle, technical economics,
  allocation evidence, forecasts, variance analysis, and optimization cases.
- `fin-hub` owns authoritative booked financial facts, budgets, commitments,
  burn, runway, and viability signals.
- Workload repositories own demand meaning and service requirements.
- Cluster and platform repositories own provisioning, operations, and source
  telemetry.
- Human authorities approve contractual commitments and material lifecycle
  changes.

This workplan defines and validates interfaces. Cross-repository implementation
must be handed off as work records in the repository that owns the source.

## T01 — Define the portfolio and lifecycle model

```task
id: RESOURCE-WP-0003-T01
status: done
priority: high
state_hub_task_id: "9c396da2-9cae-4681-8d7e-3ebcbf9db29f"
```

Define the minimum resource classes, lifecycle states, ownership fields,
capacity forms, provider/account identity, shared-versus-dedicated placement,
tenant and workload attribution, contract dates, and evidence provenance.

Reuse the current backup inventory and forecast schemas where they generalize;
identify and migrate assumptions that are storage-specific. Include validation
rules for stable identifiers and lifecycle transitions.

Done when a versioned schema and examples can represent provider-managed
object storage, self-managed Garage on VMs, cluster capacity, and a shared
platform service without ambiguous ownership or cost attribution.

Completed 2026-08-11: introduced portfolio schema v0.2 with resource classes,
management models, capacity dimensions, lifecycle states, shared and dedicated
allocation, relationships, requirements, and provenance-bearing evidence.
Migrated the real proposed backup record and added explicitly non-authoritative
Garage, Kubernetes-capacity, and shared-ingress examples. Semantic validation
covers identifier, lifecycle, allocation, capacity, and example-scope rules.
Evidence: `docs/evidence/RESOURCE-WP-0003-portfolio-model-v0.2-2026-08-11.md`.

## T02 — Record the authority and fin-hub exchange contract

```task
id: RESOURCE-WP-0003-T02
status: done
priority: high
state_hub_task_id: "efa64dce-7b5e-435e-b010-7aee9e0a410e"
```

Create an authority matrix and a versioned exchange contract with `fin-hub`.
Define the two directions separately:

- resource-control to fin-hub: resource references, allocation keys, forecasts,
  technical usage, commitment candidates, and optimization scenarios;
- fin-hub to resource-control: booked costs, credits, tax and currency treatment,
  financial commitments, budget constraints, and viability signals.

Specify period, currency, net/gross semantics, provenance, corrections,
idempotency, uncertainty, and identifiers including `resource_id`, `service_id`,
`workload_id`, `tenant_id`, `environment`, and `cost_attribution_key`.

Done when both repositories link the same reviewed contract and no field has
two authoritative writers. Coordinate with `FIN-WP-0004`.

Progress 2026-08-11: verified fin-hub commit `0034330` and its 46-test suite;
the six review remediations satisfy the authority, exact-money, typed-evidence,
idempotency, dimensional-reporting, and model-parity conditions. Added the
resource-control ratification, producer-owned planning schema, canonical
forecast exporter, booked-cost consumer validation, and reconciliation seam.
The 12-row backup forecast preflight and cross-repository compatibility check
remain before this task is complete. A real booked backup cost is deliberately
reserved for `FIN-WP-0004-T05` after procurement.

Completed 2026-08-11: all 12 resource-control producer records matched
fin-hub's executable schema and adapter output, and duplicate ingestion retained
exactly 12 planning rows. Evidence is in
`docs/evidence/RESOURCE-WP-0003-fin-hub-contract-preflight-2026-08-11.md`.
The authority contract is accepted from resource-control. The separate real
booked-cost round trip remains gated on `RESOURCE-WP-0002` procurement and is
not simulated as operational evidence.

## T03 — Inventory the first managed-infrastructure portfolio

```task
id: RESOURCE-WP-0003-T03
status: done
priority: high
state_hub_task_id: "4afbb2ea-8021-4dd7-968b-50c113a8c108"
```

Discover and register the material infrastructure serving Helix Forge,
Coulomb Social, shared Railiance services, and a representative tenant
workload. Record unknowns explicitly and separate observed resources from
inferred relationships.

For each resource, identify the authoritative workload and platform repository,
owner, lifecycle state, capacity, service objective or requirement reference,
provider/account, failure domain, contract or renewal evidence, and allocation
key. Do not retrieve or record credentials.

Done when portfolio coverage and evidence gaps are measurable and every
material discovered resource has an owner or a human-review record.

Completed 2026-08-11: registered seven evidence-backed resources covering the
Host Europe host, reef-railiance k3s capacity, Forgejo/Helix Forge, shared
applications PostgreSQL, Coulomb Social, Binky's `rapp-qonto`, and proposed
backup storage. Live read-only observation confirmed capacity, current
workloads, PVCs, and the shared single-host/local-storage failure domain.
Unknown commercial, utilization-history, labor, and allocation facts remain
explicit and are assigned to authoritative repository owners in
`data/portfolio-coverage-2026-08-11.json`. Evidence:
`docs/evidence/RESOURCE-WP-0003-initial-portfolio-discovery-2026-08-11.md`.

## T04 — Delegate demand and telemetry evidence

```task
id: RESOURCE-WP-0003-T04
status: done
priority: high
state_hub_task_id: "b4053889-69fd-4e3c-888b-0764eee2e9e4"
```

Create scoped work records in the authoritative workload and platform
repositories for missing demand declarations, service objectives, capacity,
utilization, reliability, and allocation-driver evidence. Initial targets are
`helix-forge`, `coulomb-social`, `railiance-cluster`, `rail-kubernetes`,
`rail-knative`, and `railiance-platform`; add only repositories supported by
the inventory evidence.

Each handoff must define a stable non-secret interface and acceptance evidence,
not prescribe unrelated internal implementation.

Done when all required source evidence is either available through a versioned
interface or represented by a live delegated work record with an owner.

Completed 2026-08-11: created and registered repository-local evidence plans
`RAIL-HO-WP-0008`, `RAIL-BS-WP-0014`, railiance-forge
`RAILIANCE-WP-0002`, railiance-platform `RAILIANCE-WP-0016`,
`CSOC-WP-0005`, and `RAPP-QONTO-WP-0002`. The booked-cost boundary remains in
fin-hub and is linked to existing `FIN-WP-0004-T04..T06`. The exact State Hub
workplan identifiers are recorded in
`data/portfolio-coverage-2026-08-11.json`. No duplicate plan was created in
`helix-forge`, `rail-kubernetes`, or `rail-knative`: their relevant evidence is
owned respectively by railiance-forge, railiance-cluster, and the workload plus
cluster layers.

## T05 — Generalize forecast-to-actual control

```task
id: RESOURCE-WP-0003-T05
status: done
priority: high
state_hub_task_id: "76986764-5e23-4e51-aaed-6bbb92d08915"
```

Generalize the immutable forecast and monthly actual-observation controls from
`RESOURCE-WP-0002`. Support resource-specific usage proxies, fixed and elastic
capacity, internal and external labor, infrastructure cost, booked cost
references, allocation methods, service-level constraints, and low/base/high
uncertainty.

Classify variance as demand, provider price, allocation, labor, model, or
data-quality error. Preserve the original forecast and create explicit
revisions rather than overwriting it.

Done when the same mechanism can evaluate at least storage, VM or cluster
compute, and one shared platform service.

Completed 2026-08-11: added the generic immutable control-cycle schema and
comparator, controlled six-way variance attribution, revision and booked-fact
references, and paired contract examples for elastic storage, fixed cluster
compute, and the hybrid shared apps-pg service. The examples are illustrative,
not operational facts. Evidence:
`docs/evidence/RESOURCE-WP-0003-generalized-control-cycle-2026-08-11.md`.

## T06 — Produce and govern optimization cases

```task
id: RESOURCE-WP-0003-T06
status: done
priority: medium
state_hub_task_id: "08d5a687-6ce4-4bbf-950a-9682b1f7b003"
```

Define the review cadence and decision template for rightsizing,
consolidation, commitment, renewal, migration, retirement, and provider
switching. Every recommendation must show baseline, alternative, one-time
cost, recurring infrastructure and labor cost, utilization, uncertainty,
service-level constraints, failure domains, exit path, and expected payback.

Validate the process using the backup case and at least one non-storage
portfolio candidate. Send financial implications to `fin-hub`; delegate any
approved implementation to the owning platform or workload repository.

Done when recommendations are reproducible from evidence and their eventual
outcomes feed the next forecast cycle.

Completed 2026-08-14: added the optimization-case schema, a fail-closed
evaluator, and the cadence and decision template in `docs/optimization-cases.md`.
Every option, baseline included, must present all ten decision fields; one
unknown blocks the comparison. Validated on the storage case, where Hetzner
computes fully and loses to Scaleway by EUR 29.14 per month on operator labour
rather than storage price while Host Europe blocks on four named gaps, and on
the non-storage reef-railiance k3s rightsizing case, which reports genuinely low
utilization and still refuses to recommend because the railiance01 booked price
is unknown and the utilization figure is a single sample. Neither case decides:
procurement remains `RESOURCE-WP-0002-T03`, and the cluster unknowns are
delegated to `RAIL-HO-WP-0008` and `RAIL-BS-WP-0014`. Evidence:
`docs/evidence/RESOURCE-WP-0003-optimization-cases-2026-08-14.md`.

## T07 — Establish portfolio reporting and operating cadence

```task
id: RESOURCE-WP-0003-T07
status: done
priority: medium
state_hub_task_id: "3927e658-6807-4737-ae15-ea1997dc210f"
```

Publish a portfolio view covering coverage, lifecycle, capacity, utilization,
forecast and actual variance, unattributed cost, renewals, risks, and open
optimization opportunities. Report missing evidence and unapportioned cost
rather than forcing false precision.

Define monthly observation, quarterly model calibration, and pre-renewal review
cadences with named inputs and consumers.

Done when an operator can identify material spend, idle or saturated capacity,
forecast error, approaching commitments, and the next evidence-backed action.

Completed 2026-08-14: added `tools/portfolio_report.py` and
`make portfolio-report`, rendering coverage, lifecycle, utilization, cost,
renewals, risks, open cases, and next actions from committed evidence only, plus
the cadence in `docs/portfolio-operating-cadence.md`. The report refuses false
precision: portfolio spend is `null` rather than a partial sum, unattributed
cost is a named list rather than a spread, and unmeasurable resources are
reported instead of dropped. Against the current portfolio it reports spend as
unknown, railiance01 and the k3s cluster as idle at 14 percent CPU and 37 percent
memory, no computable forecast error, no dated commitments but six active
resources with no contract dates at all, and six of seven resources sharing
`host:railiance01`. Evidence:
`docs/evidence/RESOURCE-WP-0003-portfolio-reporting-2026-08-14.md`.

## Acceptance

- [x] Portfolio schema and lifecycle rules cover the initial resource classes.
- [x] The fin-hub authority and exchange contract is jointly reviewed.
- [x] Helix Forge, Coulomb Social, shared Railiance, and tenant coverage is
      measured.
- [x] Missing source evidence has live delegated work records.
- [x] Forecast-to-actual control works for storage and non-storage resources.
- [x] At least two optimization cases complete the evidence-to-decision loop.
- [x] Portfolio reporting exposes unknown and unattributed values explicitly.

## Post-completion record

2026-08-14: `railiance-platform` delivered `RAILIANCE-WP-0016`, the first
delegated evidence from T04 to land. Folded in: the apps-pg resource record now
carries real capacity and the `apps-pg-dbbytes-v1` allocation driver, the first
operational control-cycle record replaced the illustrative apps-pg fixture, and
coverage moved to `data/portfolio-coverage-2026-08-14.json` with the gap marked
delivered and its three residual unknowns still open.

The real evidence exposed a design gap in the T05 schema: v0.1 required a number
for every cost field, so recording genuine usage without a booked cost was
impossible without inventing one. Schema 0.2 permits null costs, a null
unattributed amount, a technical `unattributed_share`, and null measurements;
the comparator reports unknown amounts as `data_quality` rather than computing a
variance. Existing 0.1 records were not rewritten. Evidence:
`docs/evidence/RESOURCE-WP-0003-apps-pg-evidence-foldin-2026-08-14.md`.

## Standing gate

Both optimization cases are `blocked_on_evidence` by design: the mechanism is
complete and proven, and the facts it needs are owed by other repositories.
The first *decided* case requires either the Host Europe account evidence that
`RESOURCE-WP-0002-T03` and `RAIL-HO-WP-0008` are waiting on, or the cluster
utilization history in `RAIL-BS-WP-0014`. The first real forecast-to-actual
variance requires a booked cost from `fin-hub` under `FIN-WP-0004`. None of
these is a gap in this workplan; each is a live delegated record with an owner.