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

Every estimate, usage observation, allocation, and expense evaluation in that loop is associated with exactly one financial entity. The six entities are Binky, Frontier, Railiance, Netkingdom, Helixforge, and Coulomb. They are profit centers of Binky Hedgehog GmbH (future Operational Knowledge GmbH). Railiance procures and manages IT resources; other centers consume them on the internal terms in docs/TermsOfResourceProcurement.md.

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, financial entity, 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, tenants, and financial entities. Allocation evidence is not customer billing. Internal transfer prices (Railiance delivered cost plus published markup) are settlement evidence, not booked spend.
• 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, financial_entity_id, procuring_entity_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, cost-attribution key, and a consuming financial entity (or an explicit unattributed gap). Silent default to Railiance or Binky is forbidden.
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. Inventory stores secret: handles only.
12. Operating attributes stay on the reef. Endpoints, buckets, member lists, and kubeconfig paths are cited as reef: references (docs/operational-reference-convention.md). This repository does not operate the resource. Compute substrate: reef-railiance. Object-store substrate for backup: reef-storage, not an add-on to the home reef.

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.