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

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

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