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

id	type	title	domain	repo	status	owner	topic_slug	created	updated	related	state_hub_workstream_id
RESOURCE-WP-0003	workplan	Establish managed-infrastructure portfolio control	financials	resource-control	finished	codex	railiance	2026-08-10	2026-08-14	RESOURCE-WP-0002 FIN-WP-0004	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

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

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

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

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

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

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

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

• Portfolio schema and lifecycle rules cover the initial resource classes.
• The fin-hub authority and exchange contract is jointly reviewed.
• Helix Forge, Coulomb Social, shared Railiance, and tenant coverage is measured.
• Missing source evidence has live delegated work records.
• Forecast-to-actual control works for storage and non-storage resources.
• At least two optimization cases complete the evidence-to-decision loop.
• 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.