147 lines
6.5 KiB
Markdown
147 lines
6.5 KiB
Markdown
# 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?
|