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

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