Draft resource cost authority contract
This commit is contained in:
parent
8338c501ed
commit
2895077b8c
4 changed files with 170 additions and 5 deletions
147
docs/fin-resource-authority-contract-v0.1.md
Normal file
147
docs/fin-resource-authority-contract-v0.1.md
Normal file
|
|
@ -0,0 +1,147 @@
|
|||
# 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?
|
||||
Loading…
Add table
Add a link
Reference in a new issue