Fin-hub ↔ resource-control authority contract v0.1

Status: draft for joint review
Owners: fin-hub / resource-control
Workplans: FIN-WP-0004-T01, RESOURCE-WP-0003-T02

Boundary

One observed amount may appear in both systems, but only as an authoritative financial fact in fin-hub and as a referenced projection used for technical analysis in resource-control. Resource-control never posts a forecast, allocation, estimate, or variance as booked spend. Fin-hub never invents resource identity, technical utilization, or allocation-driver evidence.

Customer billing basis is separate from both provider booked cost and technical allocation. Fin-hub may compute it from authoritative price and cost evidence, but legal invoices, bookkeeping, and payments stay external.

Authority matrix

Concept	Authoritative writer	Consumer/projection	Rule
Provider invoice or booked-cost row	fin-hub	resource-control	Immutable source identity; corrections reference the prior fact.
Credit, discount, tax, net/gross treatment	fin-hub	resource-control	Never reconstructed from resource-control estimates.
Budget, financial commitment, burn, runway	fin-hub	resource-control	Exported as dated constraints/signals, not copied ledgers.
Engagement price and customer margin	fin-hub	reporting/export consumers	A price is not an invoice or payment.
Resource and provider-resource identity	resource-control	fin-hub	Stable external references; fin-hub does not own the catalog.
Workload/tenant/resource relationships	resource-control, sourced from owning workload/platform repos	fin-hub	Unknown relationships remain explicit.
Technical usage and utilization	resource-control, sourced from platform telemetry	fin-hub	Observation period and evidence provenance are required.
Allocation method, driver and result	resource-control	fin-hub	Allocation never becomes booked cost; totals reconcile to referenced facts.
Demand/cost forecast and uncertainty	resource-control	fin-hub	Immutable versions; never represented as actual spend.
Optimization scenario or commitment candidate	resource-control	fin-hub/human authority	Candidate only until approved and recorded by fin-hub/human authority.
Legal commitment approval	human financial authority	both	Neither service may approve contractual terms.

Shared identifiers

Exchange records use opaque strings. Each producer validates its own native identifier and consumers preserve it byte-for-byte.

financial_fact_id: fin-hub identity for a booked cost, credit, or correction.
resource_id: resource-control identity (resource:…).
provider_resource_id: provider-native reference when non-secret.
service_id, workload_id, tenant_id, environment: optional join axes; absence is represented as null, never an invented placeholder.
cost_attribution_key: an external join key. Client workloads use fin-hub's validated client:<id>|app:<id>|instance:<id> form; infrastructure-wide keys owned by resource-control retain their own versioned namespace.

cost_attribution_key is not globally sufficient identity. Every financial exchange also carries financial_fact_id, period, currency, and provenance; every technical exchange carries its record ID and resource/workload context.

Fin-hub → resource-control: booked-cost evidence

Minimum envelope:

{
  "schema_version": "0.1",
  "record_type": "booked_cost",
  "financial_fact_id": "opaque",
  "correction_of": null,
  "source_type": "provider_invoice",
  "provider": "opaque-provider-id",
  "provider_account_ref": null,
  "accounting_period": "YYYY-MM",
  "service_period_start": "YYYY-MM-DD",
  "service_period_end": "YYYY-MM-DD",
  "currency": "EUR",
  "net_amount": 0,
  "tax_amount": 0,
  "gross_amount": 0,
  "credit_amount": 0,
  "resource_id": null,
  "service_id": null,
  "workload_id": null,
  "tenant_id": null,
  "environment": null,
  "cost_attribution_key": null,
  "source_evidence_ref": "non-secret opaque reference",
  "recorded_at": "RFC3339 timestamp"
}

Delivery is idempotent on financial_fact_id. Corrections append a new record with correction_of; consumers retain both and calculate the effective value. Unknown attribution stays null and remains visible in reconciliation.

Resource-control → fin-hub: planning and allocation evidence

Minimum common envelope:

{
  "schema_version": "0.1",
  "record_type": "forecast|allocation|usage|optimization|commitment_candidate",
  "record_id": "opaque",
  "revision_of": null,
  "resource_id": "resource:opaque",
  "service_id": null,
  "workload_id": null,
  "tenant_id": null,
  "environment": "production",
  "cost_attribution_key": "opaque",
  "period_start": "YYYY-MM-DD",
  "period_end": "YYYY-MM-DD",
  "currency": "EUR",
  "scenario": "low|base|high|observed",
  "amount": 0,
  "uncertainty": null,
  "method": "versioned method identifier",
  "assumptions": [],
  "source_evidence": [],
  "created_at": "RFC3339 timestamp"
}

Record-specific schemas add usage units, allocation drivers and shares, service constraints, or optimization-case economics. Delivery is idempotent on record_id; revisions are append-only. Fin-hub stores these as planning or analytical evidence and never in its booked-cost ledger.

Reconciliation invariants

Each booked financial fact has exactly one authoritative fin-hub record.
A resource-control allocation references the fact(s) it allocates and its shares plus explicit residual reconcile to the referenced effective total.
Currency conversion is a separate, provenance-bearing transformation; no implicit conversion occurs during joins.
Forecasts and commitment candidates cannot change burn, spend, or committed balances until the appropriate authority records the resulting fact.
Duplicate delivery changes no totals. Corrections and revisions never overwrite their predecessors.
Missing joins, unknown tax semantics, and unattributed residuals are observable data-quality states, not zero values.

Review questions

Should client attribution keys and infrastructure allocation keys share one namespaced grammar, or remain explicitly separate formats?
Which repository assigns service_id and workload_id where no workload repository already owns them?
Does resource-control's actual record type mean technical observation only, or should it be renamed to prevent confusion with fin-hub booked actuals?
Which transport and schema registry become canonical for v0.1 after the authority matrix is accepted?

6.5 KiB Raw Blame History