resource-control/INTENT.md

# INTENT — resource-control

## Why this repository exists

Railiance operates a managed-infrastructure portfolio for its own control
plane, shared platform services, Helix Forge, Coulomb Social, and other tenant
workloads. The portfolio combines provider-managed products, rented compute,
self-managed services, cluster capacity, storage, networking, databases, and
licenses. These resources create recurring infrastructure and labor cost,
capacity limits, operational dependencies, renewal decisions, and exit risk.

Invoices, provider consoles, deployment repositories, and monitoring systems
each expose only part of that picture. `resource-control` is the lifecycle cost
and resource control plane that connects workload demand, infrastructure
capacity, purchasing alternatives, actual utilization, actual cost, service
requirements, and optimization decisions.

Its control loop is:

> demand -> estimate -> compare -> approve -> procure -> commission -> allocate
> -> monitor -> optimize -> renew, migrate, or retire -> learn from variance

`resource-control` supports each stage with evidence and recommendations. It
does not silently assume authority to sign contracts, spend money, deploy
workloads, or operate services.

## Portfolio coverage

The controlled portfolio includes:

- Railiance control-plane and shared platform infrastructure;
- internal federation workloads, including Helix Forge and Coulomb Social;
- tenant-dedicated resources and shared resources attributable to tenants;
- provider-managed resources and self-managed services on rented capacity;
- proposed, ordered, commissioned, active, suspended, retiring, and retired
  resources; and
- compute, storage, networking, Kubernetes capacity, databases, managed
  services, and relevant licenses.

Host Europe, Scaleway, and Hetzner are the initial comparison baseline, not a
permanent allow-list. Other providers and self-managed architectures belong in
the same model when they can satisfy the requirements. Adding a provider
requires evidence; retaining one requires continuing value.

## What it owns

- A provider-neutral portfolio inventory of purchased, shared, dedicated,
  proposed, and retired resources.
- Resource identity, provider, account, region, service class, capacity,
  lifecycle, contract term, renewal or cancellation window, owner, workload,
  tenant, environment, and cost-attribution key.
- Demand and capacity forecasts derived from workload requirements.
- Comparable total-cost models for provider-managed and self-managed options,
  separating infrastructure, usage, internal labor, external services,
  migration, support, tax, commitment, and switching cost.
- Technical usage, utilization, saturation, reliability, and service-level
  evidence projected from the systems that produce it.
- Explainable allocation of shared resource consumption and cost to services,
  workloads, environments, and tenants. Allocation evidence is not customer
  billing.
- Unit economics and periodic rightsizing, consolidation, commitment,
  migration, renewal, retirement, and provider-switching recommendations.
- Forecast-to-actual variance control: preserve assumptions and predictions,
  compare them with observed usage, labor, capacity, and booked cost, classify
  errors, and refine future estimates without rewriting history.
- Decision records, procurement evidence, acceptance criteria, and exit plans
  for material infrastructure commitments.

## Authority and delegation

`resource-control` integrates evidence from authoritative owners; it does not
become the implementation repository for the whole control loop.

- Workload repositories such as `helix-forge`, `coulomb-social`, and `rapp-*`
  own workload behavior, demand declarations, service objectives, retention
  requirements, and workload-specific operating procedures.
- `railiance-cluster`, `rail-kubernetes`, `rail-knative`, and
  `railiance-platform` own provisioning, deployment governance, operations,
  and the production of infrastructure telemetry in their respective scopes.
- `fin-hub` owns booked financial facts, credits, tax and currency treatment,
  budgets, commitments, burn rate, runway, and financial viability signals.
- Human financial and service authorities approve purchases, contractual
  commitments, migrations, and retirements where required.
- Approved OpenBao and credential-broker lanes own provider credentials,
  payment instruments, and other secrets.

Delegated repositories should expose stable, provenance-bearing interfaces
rather than duplicate authority. The common join should support at least
`resource_id`, `service_id`, `workload_id`, `tenant_id`, `environment`,
`cost_attribution_key`, provider account, accounting period, and source
evidence where applicable.

## Relationship with fin-hub

`resource-control` answers **which concrete resources are required, purchased,
used, attributable, and replaceable, and how their technical economics can be
improved**. `fin-hub` answers **what was financially booked, what the federation
can afford, what commitments exist, what its burn rate and runway are, and when
financial pressure must change priorities**.

`resource-control` publishes resource identity, allocation keys, demand and
cost forecasts, technical usage, commitment candidates, and optimization
scenarios to `fin-hub`. `fin-hub` publishes authoritative booked-cost evidence,
active financial commitments, budget constraints, and viability signals to
`resource-control`.

There is no competing invoice or budget ledger here. An actual-cost view in
`resource-control` is a provenance-bearing projection joined to concrete
resources and utilization; the booked financial fact remains authoritative in
`fin-hub`.

## Operating principles

1. **Provider-neutral requirements first.** Define service level, durability,
   recovery, residency, performance, capacity, isolation, and exit needs before
   comparing products.
2. **Optimize within constraints.** Cost reduction must preserve accepted
   security, sovereignty, reliability, recoverability, performance, operator
   capacity, and tenant-isolation requirements.
3. **Total cost, not headline price.** Include traffic, requests, minimum
   charges, tax, support, internal and external labor, migration, idle capacity,
   and recovery-test cost.
4. **No unowned spend or capacity.** Every resource has an accountable owner,
   purpose, lifecycle state, workload or shared-allocation rule, environment,
   and cost-attribution key.
5. **Allocation must be explainable.** Shared costs identify their driver,
   uncertainty, unapportioned remainder, and source evidence.
6. **Forecasts are falsifiable records.** Material estimates preserve their
   expected cost, usage proxies, capacity, labor, service level, assumptions,
   uncertainty, and observation period.
7. **Learn from actuals.** Variance is classified as demand, price, allocation,
   labor, model, or data-quality error and feeds the next forecast cycle.
8. **No untested resilience claims.** Backup is accepted only after a restore;
   failover is accepted only after an exercise; capacity is accepted only after
   usable capacity and constraints are verified.
9. **Exit and renewal are part of procurement.** Record data export, migration
   path, cancellation window, renewal trigger, and credential revocation before
   commitment.
10. **Avoid correlated failure silently.** Shared failure domains may be
    intentional, but they and their compensating controls must be explicit.
11. **Credentials stay elsewhere.** Provider keys and billing credentials live
    in approved secret-custody lanes, never in this repository.

## What it does not own

- Budget authority, runway policy, authoritative financial transactions, or
  invoice custody.
- Contract signature, payment, or autonomous procurement approval.
- Workload manifests, application behavior, or service-specific operating and
  backup procedures.
- Provider credentials, payment instruments, or secret delivery.
- Cluster and platform deployment governance or day-to-day service operation.
- Application retention and service-level policy; it verifies feasibility and
  exposes their resource and cost consequences.
- Customer invoicing, taxation, or a tenant billing system.

## Initial proving cases

The first end-to-end proving case is off-host object storage for
`rapp-postgres` continuous WAL archiving, physical base backups, and a separate
logical-backup copy. It deliberately exercises demand forecasting, elastic and
self-managed architecture comparison, infrastructure and labor cost,
procurement evidence, resource acceptance, restore verification, utilization,
booked-cost integration, forecast error, and provider exit.

The resulting control model must generalize next to the infrastructure serving
Helix Forge, Coulomb Social, shared Railiance services, and tenant workloads;
backup is an example of the intent, not its boundary.