---
id: FIN-WP-0006
type: workplan
title: "Consume resource-control internal transfer settlement"
domain: financials
repo: fin-hub
status: finished
flavor: residual
owner: codex
topic_slug: financials
created: "2026-08-14"
updated: "2026-09-27"
related:
  - FIN-WP-0004
  - RESOURCE-WP-0005
origin: residual
origin_ref: RESOURCE-WP-0005
state_hub_workstream_id: "e9413a20-5b11-50ff-ba21-15215841cf11"
---

# FIN-WP-0006 — consume internal transfer settlement

## Goal

Accept proposed internal transfer charges and credit-state records from
`resource-control` without taking resource authority or creating a second
ledger. Recognize internal payments as booked facts joined by
`financial_fact_id`, `financial_entity_id`, and period.

Origin: `RESOURCE-WP-0005-T07`. Terms live in
`resource-control/docs/TermsOfResourceProcurement.md`. Outbound shape:
`resource-control/schemas/settlement-statement.schema.json`.

## Boundaries

- `resource-control` owns transfer-price arithmetic, statements, and
  consumption mode.
- `fin-hub` owns booked provider cost, tax, recognized payments, and any
  later DATEV-facing internal settlement posting.
- A settlement statement is not booked spend.

## T01 — Join proposed transfer charges

```task
id: FIN-WP-0006-T01
status: done
flavor: residual
priority: high
state_hub_task_id: "9ef3fab5-51a6-57ef-8121-b9714298c502"
```

Document and implement the inbound join for resource-control settlement
statements. Preserve `financial_entity_id`, `period`, `terms_version`,
and statement identity. Reject any path that would post the statement as
a provider invoice.

Done when an inbound fixture can be stored as a referenced projection
and `exchange_health` shows statements lacking a payment join as a
visible residual, not as booked cost.

Completed 2026-09-27: added `SettlementStatement`
(`src/fin_hub/schemas/exchange.py`) matching resource-control's v0.1
`settlement-statement.schema.json`, with a dedicated
`settlement_statements` table (`services/exchange.py`) that never touches
`ledger_entries`. `ingest_settlement_statement` validates and stores each
statement keyed by `financial_entity_id` + `procuring_entity_id` + `period`
+ `statement_date`, idempotent on identical resubmission, and superseding
the prior current statement for the same entity/period pair on a later
`statement_date`. `exchange_health` now emits
`settlement_awaiting_payment_join` (severity `warning`) for any current
statement with `payment_recognition: "unknown"`, listing its outstanding
amount as a residual rather than booked cost.
`current_settlement_statements` exposes the stored projection for
reporting. CLI: `finhub ledger ingest-settlement` and
`finhub ledger settlements`. Fixture:
`tests/fixtures/settlement-statement-2026-08.json`. Tests:
`tests/test_exchange.py::test_settlement_statement_*` and
`::test_exchange_health_surfaces_settlement_without_payment_join_as_residual`.
Full suite: 102 passed.