Add client billing and cost evidence workplans

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

@@ -0,0 +1,177 @@
+---
+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.