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

---
id: FIN-WP-0004
type: workplan
title: "Establish the resource cost evidence contract"
domain: infotech
repo: fin-hub
status: proposed
owner: codex
topic_slug: financials
created: "2026-08-10"
updated: "2026-08-10"
related:
  - FIN-WP-0001
  - RESOURCE-WP-0002
  - RESOURCE-WP-0003
state_hub_workstream_id: "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

```task
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

```task
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

```task
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

```task
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

```task
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

```task
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.