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

Status: authority boundary reviewed; v0.1 implementation acceptance pending

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.

Identifier decisions

Client and infrastructure attribution identifiers remain distinct, versioned namespaces under this common envelope.
Native service/workload identity stays with its owning repository; resource-control may issue a clearly scoped portfolio surrogate only when no native authority exists.
usage_observation is the technical observation record. “Booked actual” is reserved for fin-hub financial facts.
Each producer owns its outbound schema. This contract pins compatible versions and reconciliation; transport is selected after the backup round trip.

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

Minimum envelope:

{
  "schema_version": "0.1",
  "record_type": "booked_cost",
  "financial_fact_id": "opaque",
  "correction_of": null,
  "adjustment_kind": "charge",
  "source_type": "provider_invoice",
  "source_document_id": "opaque",
  "source_line_id": "opaque",
  "content_fingerprint": "sha256",
  "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": "10.00",
  "discount_amount": "0.00",
  "tax_status": "known",
  "tax_amount": "1.90",
  "gross_amount": "11.90",
  "adjustment_amount": "0.00",
  "effective_amount": "11.90",
  "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.

Money uses decimal strings at two fractional digits, ISO 4217 currency, and round-half-even. net_amount, discount_amount, and gross_amount are non-negative. When tax is known, gross = net - discount + tax; unknown tax is represented by tax_status: unknown and tax_amount: null without inventing a net/tax split. adjustment_amount is signed and effective = gross + adjustment; credits, refunds, and reversals require a negative adjustment and an explicit predecessor. The executable schema is fin_hub.schemas.exchange.BookedCostEvidence.

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

Minimum common envelope:

{
  "schema_version": "0.1",
  "record_type": "forecast|allocation|usage_observation|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",
  "source_evidence": [],
  "created_at": "RFC3339 timestamp"
}

The common envelope deliberately has no generic amount. Executable, record-specific schemas in fin_hub.schemas.exchange define:

ForecastEvidence: scenario/version, uncertainty, assumptions, and separate infrastructure, internal-labor, external-service, setup, and other costs;
UsageObservation: named decimal measures with explicit units and no booked cost semantics;
AllocationEvidence: referenced financial facts, method, allocated amount, target shares, and explicit residual that must reconcile to one;
OptimizationEvidence: baseline/alternative breakdown, one-time cost, and expected period savings; and
CommitmentCandidate: setup/recurring cost, cadence, term, and immutable candidate approval status.

Delivery is idempotent on record_id; revisions are append-only and must reference the current record of the same type. Fin-hub stores these in planning_evidence, 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.

Acceptance status

Resource-control accepted the authority boundary in principle on 2026-08-11. The review is preserved at history/2026-08-11-resource-control-review-fin-wp-0004.md. Contract v0.1 is not accepted until the implementation-integrity tasks and reconciled backup round trip pass.

8.2 KiB Raw Blame History