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: active
owner: codex
topic_slug: financials
created: "2026-08-10"
updated: "2026-08-11"
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 active companion to `RESOURCE-WP-0003` incorporates resource-control's
2026-08-11 review. The authority boundary is accepted in principle; the v0.1
exchange remains unapproved until T02, T03, T05, and T07–T09 satisfy the
review conditions.

## T01 — Review and record the authority boundary

```task
id: FIN-WP-0004-T01
status: done
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.

Progress 2026-08-10: drafted
`docs/fin-resource-authority-contract-v0.1.md` from both repositories' current
models, resource schemas, forecast/actual controls, and workplans. The draft
defines the authority matrix, directional envelopes, identifiers, correction
and idempotency rules, reconciliation invariants, and four review questions.
Joint resource-control review remains required before completion.

Review 2026-08-11: resource-control accepted the authority boundary in
principle and requested changes before v0.1 approval. The timestamped result is
`history/2026-08-11-resource-control-review-fin-wp-0004.md`. T02 and T03 own
the envelope refinements; T07-T09 own the implementation-integrity findings.
Align `INTENT.md` and remove the proposed/active lifecycle contradiction as
part of incorporating the joint review.

Completed 2026-08-11: incorporated all four review decisions into the
contract, aligned `INTENT.md`, and corrected lifecycle language. The authority
boundary is jointly reviewed and accepted in principle; implementation
acceptance remains gated by T05.

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

```task
id: FIN-WP-0004-T02
status: done
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`.

Completed 2026-08-11: `BookedCostEvidence` defines decimal-string money,
round-half-even precision, net/discount/tax/gross/effective relationships,
unknown-tax handling, signed adjustment semantics, stable fact/document/line
identity, fingerprints, corrections, provenance, and join axes. Current
HostEurope facts project through this schema without raw invoice content.

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

```task
id: FIN-WP-0004-T03
status: done
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.

Completed 2026-08-11: added distinct forecast, usage-observation, allocation,
optimization, and commitment-candidate schemas plus an idempotent,
append-only `planning_evidence` store outside the booked ledger. The adapter
successfully ingested all 12 rows of resource-control's live PostgreSQL backup
forecast into a temporary fin-hub ledger.

## 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.

## T07 — Correct cost-report dimensions and currency safety

```task
id: FIN-WP-0004-T07
status: done
priority: high
state_hub_task_id: "406ce484-db7f-4bb9-b3b3-23217c052e08"
```

Correct service and monthly aggregation so no report adds amounts across
currencies or silently combines environments. Define and test the canonical
dimensions for service, attribution, period, environment, and currency views.
Expose residual and unattributed totals under the same rules.

Done when mixed-currency and mixed-environment fixtures remain separate, all
rollups reconcile per currency, and no result inherits a misleading currency
or environment label from its first row.

Completed 2026-08-11: service buckets now key on service, environment, and
currency; attribution buckets include environment and currency; period totals
are currency-separated; and explicit unattributed residuals use the same
dimensions. Mixed fixtures are covered by regression tests.

## T08 — Establish idempotent booked-fact imports and corrections

```task
id: FIN-WP-0004-T08
status: done
priority: high
state_hub_task_id: "aded815d-75a2-4496-9676-b44b5e4dc49a"
```

Replace file-path-and-mtime deduplication as the financial identity boundary.
Define stable `financial_fact_id`, source-document and source-line identity,
content fingerprint, duplicate-delivery behavior, and append-only correction,
reversal, and replacement semantics. Preserve raw provenance without storing
secret invoice material in exchange records.

Done when unchanged, renamed, touched, corrected, and force-reimported inputs
cannot double-count a fact; corrections change effective totals exactly once
while predecessors remain auditable.

Completed 2026-08-11: ledger rows now carry stable financial-fact,
source-document, and source-line identities, content fingerprints,
`correction_of`, and single-current state. Renamed, touched, duplicate, and
forced unchanged deliveries are idempotent; changed facts require an explicit
forced correction and effective totals include exactly one current version.
`reverse_financial_fact` appends a provenance-bearing reversal that zeroes the
effective fact without deleting its predecessor.

## T09 — Unify money and engagement-price domain invariants

```task
id: FIN-WP-0004-T09
status: done
priority: high
state_hub_task_id: "c52d79b9-cbad-4d06-bd54-9b06125e12a0"
```

Use one domain validation path for SQLite commands and SQLAlchemy models.
Enforce attribution-key consistency, valid periods, normalized currency,
non-negative engagement prices, decimal money, effective-date rules, source
provenance, and a concurrency-safe append-only revision chain. Add equivalent
database constraints where practical.

Done when both persistence paths reject the same invalid records, concurrent
revisions cannot create two current prices for one basis, and calculations use
documented precision and rounding.

Completed 2026-08-11: shared money, currency, period, attribution, and price
validation now serves SQLite and SQLAlchemy. Calculations use integer minor
units or `Decimal(18,2)` with round-half-even; price revisions use immediate
transactions and partial unique current-basis indexes. ORM constraints cover
non-negative price, effective dates, currency, canonical attribution, and one
current reporting-month basis.

## 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.
- [ ] Cost reports never mix currency or environment dimensions.
- [ ] Booked-fact import and corrections are idempotent under changed delivery.
- [ ] SQLite and SQLAlchemy paths enforce the same money and price invariants.