fin-hub/docs/resource-cost-exchange-operations.md

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.