183 lines
8.2 KiB
Markdown
183 lines
8.2 KiB
Markdown
# 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:
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
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.
|
|
|
|
## 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.
|