Advance resource cost evidence contract

docs/resource-cost-exchange-operations.md

@@ -0,0 +1,59 @@
+# 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.