59 lines
2.8 KiB
Markdown
59 lines
2.8 KiB
Markdown
# Resource-cost exchange operations
|
|
|
|
This runbook operates contract v0.1 between fin-hub and resource-control. The
|
|
authority matrix remains in `fin-resource-authority-contract-v0.1.md`.
|
|
|
|
## Compatibility and delivery
|
|
|
|
- Producers pin `schema_version`. A consumer rejects an unknown version; it
|
|
must not discard fields or reinterpret a new version as v0.1.
|
|
- Delivery identity is `financial_fact_id` for booked facts and `record_id` for
|
|
planning evidence. Redelivery is idempotent; different content under the
|
|
same ID is rejected.
|
|
- Corrections and forecast/allocation revisions are append-only and point to
|
|
the current predecessor. Consumers retain superseded records for audit and
|
|
variance work.
|
|
- Resource joins use an explicit mapping from stable `financial_fact_id` to a
|
|
resource-control-owned `resource_id`. Provider labels, filenames, and prose
|
|
are not resource identity. For the current compute case the target ID is
|
|
`resource:hosteurope:railiance01`.
|
|
- Currency conversion is never implicit. Reconciliation is performed per
|
|
currency and effective period.
|
|
|
|
## Reconciliation procedure
|
|
|
|
For each delivery window, record and compare on both sides:
|
|
|
|
1. current booked-fact IDs, count, effective totals per currency, correction
|
|
edges, and source-evidence references;
|
|
2. planning record IDs/count, current revisions, forecast totals, allocation
|
|
fact references, and explicit residuals;
|
|
3. the join set and missing resource IDs, without copying resource authority
|
|
into fin-hub;
|
|
4. returned variance/optimization IDs and provenance, confirming none was
|
|
inserted as a second booked financial fact.
|
|
|
|
Duplicate replay must leave all counts and totals unchanged. A correction must
|
|
replace the effective total exactly once while preserving the predecessor.
|
|
|
|
## Operator visibility
|
|
|
|
`exchange_health` reports only bounded metadata and amounts. It surfaces:
|
|
|
|
- rejected planning deliveries by claimed ID and safe validation metadata;
|
|
- booked facts lacking both a resource binding and cost attribution;
|
|
- current forecasts whose effective period has ended; and
|
|
- allocations that reference a missing current financial fact.
|
|
|
|
Rejected payload bodies are not retained. Only a content fingerprint, claimed
|
|
record ID/type, safe validation locations/codes, delivery count, and timestamp
|
|
are stored. Resolve error-severity issues before reconciliation; warnings need
|
|
an explicit disposition. Retain the health report with the round-trip evidence.
|
|
|
|
## Upgrade and review
|
|
|
|
Add a new schema alongside v0.1, publish fixtures, and dual-run it. Compare
|
|
canonical IDs, counts, money totals, corrections/revisions, joins, exceptions,
|
|
and provenance. Resource-control and fin-hub owners jointly approve the
|
|
compatibility window and removal date. Roll back by selecting the prior pinned
|
|
producer/consumer version; never rewrite existing evidence to downgrade it.
|