tegwick
debe67edf0
Assistant: codex Assistant-Model: gpt-5.6-sol Assistant-Session: 01a053ff-1d6f-7fe2-ac1c-a6eb40a42a0c
108 lines
5.4 KiB
Markdown
108 lines
5.4 KiB
Markdown
# 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
|