Advance resource cost evidence contract

docs/fin-resource-authority-contract-v0.1.md

@@ -160,6 +160,24 @@ 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.
 
+## Fin-hub → resource-control: bounded financial constraints
+
+`FinancialConstraintSignal` exposes only the financial context needed to rank
+a procurement or optimization case: applicable budget ceiling, active
+commitment amount, budget utilization, and runway pressure. Each signal has a
+stable content-derived ID, exact currency and effective period, optional
+resource/service/environment scope, non-secret provenance, and generation
+time.
+
+Budget ceilings and active commitments are labelled `policy_constraint`.
+Budget utilization and runway are labelled `informational` or
+`informational_warning` according to the current threshold. Consumers must not
+turn an informational signal into an approval gate, nor reproduce fin-hub's
+budget, burn, or runway calculations. Missing authoritative values produce no
+signal rather than a synthetic zero. The projection carries no payment
+credentials, private invoice data, unrelated ledger rows, or procurement
+authority.
+
 ## Reconciliation invariants
 
 1. Each booked financial fact has exactly one authoritative fin-hub record.

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.