# 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:

```json
{
  "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:

```json
{
  "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

1. Each booked financial fact has exactly one authoritative fin-hub record.
2. A resource-control allocation references the fact(s) it allocates and its
   shares plus explicit residual reconcile to the referenced effective total.
3. Currency conversion is a separate, provenance-bearing transformation; no
   implicit conversion occurs during joins.
4. Forecasts and commitment candidates cannot change burn, spend, or committed
   balances until the appropriate authority records the resulting fact.
5. Duplicate delivery changes no totals. Corrections and revisions never
   overwrite their predecessors.
6. 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?