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	active	codex	financials	2026-08-10	2026-08-11	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 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

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

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

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

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.

T07 — Correct cost-report dimensions and currency safety

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

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

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.