fin-hub/README.md

# Fin Hub

Resource viability hub for the FOS federation — budgets, commitments, burn rate,
runway projection, and booked token / AI-plan spend.

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 import ai-plan tests/fixtures/ai-plans.csv
uv run finhub ledger commitments
uv run finhub ledger set-entitlement --provider anthropic --plan claude-max --period 2026-08 --unit plan --plan-label "Max 20x" --source vendor-plan
uv run finhub ledger plan-month --period 2026-08
uv run finhub ledger ingest-session-tokens tests/fixtures/session-tokens-2026-08.json
uv run finhub ledger session-tokens --period 2026-08
uv run finhub ledger allocate-plan --fact FACT --method measured_token_share
uv run finhub ledger plan-allocations
uv run finhub ledger effectiveness --period 2026-08
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 ledger billing-basis
uv run finhub evaluate
uv run finhub evidence --seed-fixtures
uv run finhub fabric-cutover-check --authority fabric-export.json --projection state-hub-fabric-summary.json
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.

Fabric graph authority remains in the specialized `railiance-fabric` engine.
Fin-hub publishes the financial-domain boundary and an executable State Hub
cutover gate in `docs/fabric-authority-consumer-contract-v1.md`; it does not
copy Fabric authority tables into its ledger.

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

`ledger billing-basis` produces an idempotent client-period reporting artifact.
Each record includes the current price and revision, direct and allocated cost,
margin, financial-fact/correction IDs, allocation/revision IDs, and non-secret
provenance. Residuals, non-client targets, and client costs without a price are
explicit exceptions. The artifact carries a mandatory disclaimer and never
assigns invoice numbers, performs bookkeeping, or requests/tracks payment.

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