fin-hub/workplans/FIN-WP-0002-client-attribution-and-billing-basis.md

---
id: FIN-WP-0002
type: workplan
title: "Client attribution and billing basis"
domain: financials
repo: fin-hub
status: active
owner: codex
topic_slug: financials
created: "2026-08-10"
updated: "2026-08-10"
related:
  - FIN-WP-0001
  - FIN-WP-0004
  - CUST-WP-0058
state_hub_workstream_id: "ebc1d2de-ae11-4cde-b860-047922fc74b9"
---

# FIN-WP-0002 — Client attribution and billing basis

## Goal

Extend fin-hub's reporting model from service-level cost evidence to a
client × application × instance billing basis, including engagement revenue,
margin reporting, and explainable shared-infrastructure allocation.

fin-hub remains reporting-only. It does not generate invoices, execute or
track payments, perform bookkeeping, or become authoritative for client or
resource identity. An external GoBD-capable bookkeeping/invoicing system owns
invoice generation and payment tracking.

This workplan originates the proposal from the Custodian's
`CUST-WP-0058-T06` gap assessment. T00 reconciled the earlier scope exclusion:
client-level reporting and billing-basis exports are in scope, while legal
invoice generation, bookkeeping, payment handling, and identity authority
remain out of scope.

## Reconcile scope and authority boundaries

```task
id: FIN-WP-0002-T00
status: done
priority: high
state_hub_task_id: "280ff8c9-2a82-4a40-908c-37d6ca8ce3e2"
```

Reconcile this proposal with `SCOPE.md`, which currently lists multi-tenant
customer billing as out of scope. Define the permitted boundary between
client-level financial reporting and external invoicing/bookkeeping, and
update the scope or defer this workplan explicitly.

Also align with `FIN-WP-0004` so provider booked-cost evidence, analytical
allocation, customer billing basis, and resource-control technical allocation
have one authoritative owner each and do not double-count costs.

Done when the repository scope explicitly permits the intended reporting and
export surfaces, or the workplan is blocked/deferred with an identified owner
for the capability.

Completed 2026-08-10: `SCOPE.md` now includes client-level attribution,
engagement revenue/margin reporting, and billing-basis exports, while
explicitly excluding legal invoice generation/numbering, bookkeeping,
payments, banking, and client/resource identity authority. `FIN-WP-0004`
remains the coordination point for booked-cost versus technical-allocation
authority.

## Add client attribution

```task
id: FIN-WP-0002-T01
status: done
priority: high
state_hub_task_id: "904e9edc-a434-41e6-a4c7-ebb407469514"
```

After T00, extend cost rows with a stable client × application × instance cost
attribution key. Use an explicit external string identifier initially while
preserving a later reference seam to client-hub's authoritative app-instance
identity. Do not make fin-hub the client registry.

Cover unknown/unattributed values, uniqueness and period semantics,
corrections, migrations, validation, and backward compatibility for existing
service-level records.

Completed 2026-08-10: added a canonical validated external attribution key,
optional client/application/instance columns to `ServiceCost`, HostEurope CSV
ingestion and the SQLite ledger, additive migration for existing ledgers, and
currency-safe attributed reporting alongside the backward-compatible service
view. Partial or mismatched attribution is rejected; legacy rows remain
explicitly unattributed. Covered by the full test suite and documented in
`README.md`.

## Add engagement revenue and margin reporting

```task
id: FIN-WP-0002-T02
status: done
priority: high
state_hub_task_id: "f917bb0b-f44e-4642-9130-c1a004185180"
```

After T00 and T01, model the agreed engagement price or entitlement per
reporting period and compute revenue, attributed cost, and margin by client
and application. Preserve currency, effective periods, provenance, and price
revisions; do not treat a price record as an issued invoice or received
payment.

Completed 2026-08-10: added versioned engagement-price records with stable
IDs, reporting month, currency, source provenance, and explicit append-only
revision links. The SQLite ledger and CLI now report revenue, attributed cost,
and margin by client/application/instance without representing prices as
invoices or payments. Currency mismatches cannot silently join, superseded
prices remain auditable, and duplicate prices require an explicit revision.

## Define shared-infrastructure allocation

```task
id: FIN-WP-0002-T03
status: todo
priority: medium
state_hub_task_id: "899a5c29-843c-481f-a63a-42d4d327af5d"
```

After T00 and in coordination with `FIN-WP-0004`, define an explainable
per-instance allocation method for shared infrastructure. Start with the
available namespace/resource evidence, document assumptions and residual
unattributed cost, and keep technical allocation authority outside fin-hub
where resource-control supplies it.

Test allocation totals, rounding, missing evidence, shared overhead, revised
allocations, and prevention of duplicate booked cost.

## Export a per-client billing basis

```task
id: FIN-WP-0002-T04
status: wait
priority: medium
state_hub_task_id: "b5886131-82f6-49fb-a7e3-ba47d5b627a8"
```

After T00–T03, provide an idempotent billing-basis report/export by client and
period for consumption by an external invoicing system. Include stable record
identity, attribution key, period, price basis, allocated cost, margin,
currency, corrections, and provenance.

The export must not issue invoices, assign legal invoice numbers, execute or
track payments, or represent itself as bookkeeping evidence.

## Select the external invoicing system

```task
id: FIN-WP-0002-T05
status: wait
priority: high
state_hub_task_id: "d30b606f-43c1-4610-875d-c1fe578c412c"
```

Human gate: select the external GoBD-capable bookkeeping/invoicing system and
record the integration boundary, required export fields, custody model, and
retention responsibilities. Candidate products from the gap assessment are
lexoffice and sevDesk, but selection is an operator/business decision and is
not required to settle T00–T03.

## Acceptance

- [ ] Repository scope explicitly allows the reporting and export boundary.
- [ ] Costs can be reported by client × application × instance without making
      fin-hub authoritative for client or resource identity.
- [ ] Revenue and margin are period-aware, currency-aware, and distinguishable
      from invoices and payments.
- [ ] Shared-infrastructure allocations reconcile to authoritative booked
      costs with assumptions and unattributed residuals visible.
- [ ] The billing-basis export is idempotent and contains no payment execution.
- [ ] A human records the external invoicing/bookkeeping system decision.