fin-hub/README.md

# Fin Hub

Resource viability hub for the FOS federation — budgets, commitments, burn rate,
runway projection, and token spend tracking.

Fin-hub extends `hub-core` with financial models and read surfaces. Generic hub
primitives (domains, repos, messages, progress events) come from hub-core;
fin-specific models (budget, commitment, burn rate, runway, token spend) live
here.

## Status

MVP complete (`CUST-WP-0025` T22–T26): models, CSV ingest, runway CLI, FOS
coupling, RaaS packaging draft. Operational hardening tracked in
`workplans/FIN-WP-0001-runway-operations-lane.md`.

## Quick Start

```bash
cd /home/worsch/fin-hub
uv sync
uv run pytest
uv run finhub runway --balance 12000 --monthly-burn 2100,2200,2000
uv run finhub ledger import cloud tests/fixtures/cloud-costs.csv
uv run finhub ledger set-price --client acme --application portal --instance prod-01 --period 2026-07 --amount 100 --source agreement-2026-01
uv run finhub ledger margins
uv run finhub ledger allocations
uv run finhub evaluate
uv run finhub evidence --seed-fixtures
uv run finhub serve
uv run finhub import-cloud tests/fixtures/cloud-costs.csv
uv run finhub ops-costs tests/fixtures/hosteurope.csv
```

Cross-hub coupling (`--emit`) posts non-secret progress events to dev-hub when
`STATE_HUB_API` is reachable.

## Client cost attribution

HostEurope CSV rows may include `client_id`, `application_id`, and
`app_instance_id`. All three must be present together. Fin-hub validates them
as external identifiers and derives the stable key
`client:<client_id>|app:<application_id>|instance:<app_instance_id>`; callers
must not invent a second key format. Rows without all three columns remain
explicitly unattributed for backward compatibility.

The SQLite ledger adds the attribution columns automatically when an existing
ledger is opened. The `ops-costs` report retains its per-service view and adds
an `attributions` view separated by currency. Client and application identity
remain authoritative outside fin-hub.

Engagement prices are reporting entitlements, not invoices or received
payments. A price is identified by client/application/instance, reporting
month, and currency. Corrections are append-only: pass the current record ID
to `ledger set-price --revision-of`; margin reports use the newest revision
and preserve the earlier price for auditability.

Ledger imports identify financial facts independently of filename and mtime.
Duplicate, renamed, touched, and forced unchanged deliveries do not change
totals. A changed row is rejected unless `force=True` explicitly appends a
correction; reversals use `reverse_financial_fact` and retain their predecessor.
All effective calculations use integer minor units with decimal
round-half-even normalization.

The executable resource-control exchange contract lives in
`fin_hub.schemas.exchange`. `booked_cost_projection` emits current booked facts;
`ingest_planning_evidence` stores typed forecasts, usage observations,
allocations, optimization cases, and commitment candidates outside booked
spend. `ingest_resource_forecast` adapts resource-control's v0.1 monthly backup
forecast without inventing resource identity.

Shared-infrastructure allocation remains authoritative in resource-control.
Fin-hub's `ledger allocations` command consumes current `AllocationEvidence`,
requires every referenced financial fact to be current and uniquely claimed,
checks period/environment/currency and booked totals, and calculates target and
residual amounts in integer minor units. The producer-supplied versioned method
and provenance remain visible. Deterministic largest-remainder rounding makes
all target amounts plus the explicit unattributed residual reconcile exactly
to booked cost.

## Related Workplans

- `the-custodian/workplans/CUST-WP-0025-fos-hub-bootstrap.md` — umbrella
- `canon/constitution/bootstrap-protocol_v0.1.md` — funding and roles
- `canon/projects/railiance/business-model-canvas_v0.1.md` — monetization path