# 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:|app:|instance:` 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.