fin-hub/workplans/FIN-WP-0004-resource-cost-evidence-contract.md

id	type	title	domain	repo	status	owner	topic_slug	created	updated	related	state_hub_workstream_id
FIN-WP-0004	workplan	Establish the resource cost evidence contract	infotech	fin-hub	proposed	codex	financials	2026-08-10	2026-08-10	FIN-WP-0001 RESOURCE-WP-0002 RESOURCE-WP-0003	67b6de6c-4820-4478-9789-f50260204c27

FIN-WP-0004 — resource cost evidence contract

Goal

Establish a versioned, provenance-bearing exchange between fin-hub and resource-control so booked financial facts can be joined to concrete infrastructure resources, technical utilization, forecasts, allocations, and optimization scenarios without creating competing ledgers.

fin-hub remains authoritative for booked costs, credits, tax and currency treatment, budgets, financial commitments, burn, runway, and viability signals. resource-control remains authoritative for resource identity, lifecycle, demand and capacity forecasts, technical usage, allocation evidence, unit economics, and infrastructure optimization cases.

This is a proposed companion to RESOURCE-WP-0003 and should move to ready only after both repository owners review the authority matrix.

T01 — Review and record the authority boundary

id: FIN-WP-0004-T01
status: todo
priority: high
state_hub_task_id: "6616e6a0-b0f3-4b82-a081-083891e2fb6e"

Review existing fin-hub ledger, commitment, provider-import, service-cost, burn, and runway models against the revised resource-control intent. Record one authoritative writer for each exchanged concept and identify existing fields or reports that imply duplicate authority.

Explicitly distinguish:

• provider invoice or booked-cost evidence from analytical cost allocation;
• financial commitments from technical commitment candidates;
• budgets and viability constraints from demand forecasts;
• resource-control actual-cost projections from fin-hub booked facts; and
• internal showback evidence from customer billing.

Done when the boundary is reviewed jointly with RESOURCE-WP-0003-T02 and there is no ambiguous ownership of a ledger, forecast, allocation, or resource.

T02 — Specify fin-hub to resource-control booked-cost evidence

id: FIN-WP-0004-T02
status: todo
priority: high
state_hub_task_id: "0a90dd6f-b0c9-42dc-b625-cfedf0471143"

Define a stable export or projection for authoritative booked-cost evidence. It must cover source record identity, provider and account reference, accounting and service periods, currency, net/gross and tax semantics, credits or discounts, correction relationships, provenance, and available attribution keys.

Support joins using the agreed subset of resource_id, service_id, workload_id, tenant_id, environment, and cost_attribution_key without requiring fin-hub to own the resource catalog. Unknown and unattributed values must remain explicit.

Done when representative Host Europe or other provider rows can be exported idempotently and joined without copying invoice authority into resource-control.

T03 — Specify resource-control to fin-hub planning evidence

id: FIN-WP-0004-T03
status: todo
priority: high
state_hub_task_id: "ad9dccb4-85be-4f19-b36e-2f7165a879f5"

Define ingestion for resource references, allocation evidence, low/base/high demand and cost forecasts, internal and external labor assumptions, technical usage, commitment candidates, and optimization scenarios. Preserve forecast version, observation period, uncertainty, assumptions, and source provenance.

Planning evidence must not be posted as booked spend. Define how an approved commitment candidate becomes a financial commitment and how superseded forecasts remain queryable for later variance analysis.

Done when the PostgreSQL backup forecast can enter fin-hub without being mistaken for an invoice or actual expenditure.

T04 — Expose budgets, commitments, and viability constraints

id: FIN-WP-0004-T04
status: todo
priority: medium
state_hub_task_id: "3620fc2a-be3d-40aa-b357-d7741078c192"

Define the bounded financial signals that resource-control needs when ranking procurement and optimization options: applicable budget ceiling, active commitment state, burn or runway pressure, currency basis, effective period, and signal provenance.

Do not export payment credentials, private invoice documents, or unrelated ledger detail. Consumers must be able to distinguish a policy constraint from an informational warning.

Done when resource-control can evaluate affordability and commitment pressure without reproducing fin-hub's allocator or runway logic.

T05 — Implement and reconcile the first round trip

id: FIN-WP-0004-T05
status: todo
priority: high
state_hub_task_id: "9a411734-76f6-4c8d-9a48-b5a08cf8fd1f"

Implement the smallest interfaces needed for the RESOURCE-WP-0002 backup case. Reconcile a forecast, an attributed booked-cost period, and a variance result across both repositories. Test duplicate delivery, corrections, unattributed cost, missing keys, currency semantics, and revised forecasts.

Record row counts, totals, provenance, and ownership assertions on both sides. Do not make the integration depend on mutable prose or filename conventions.

Done when the same cost is booked exactly once, projected to resource-control, joined to technical evidence, and returned as planning or variance evidence without becoming a second financial fact.

T06 — Generalize and operate the contract

id: FIN-WP-0004-T06
status: todo
priority: medium
state_hub_task_id: "a1309d51-32c3-4a9d-99f5-4dfb7abf4b3e"

Validate the contract with one non-storage resource and one shared service. Define versioning, compatibility, correction, reconciliation, data-quality, and review procedures. Add operator-facing visibility for rejected records, unattributed booked cost, stale forecasts, and reconciliation failures.

Done when the contract supports storage, compute or cluster capacity, and a shared-service allocation without changing the authority boundary.

Acceptance

• One reviewed authority matrix is linked from both repositories.
• Booked financial facts remain authoritative only in fin-hub.
• Resource identity and technical allocation remain authoritative only in resource-control.
• Forecasts cannot be confused with invoices or booked expenditure.
• Exchange records carry stable identifiers, periods, provenance, and correction semantics.
• Backup completes a reconciled round trip with no double counting.
• At least one non-storage and one shared-service case validate the generalized contract.