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

id	type	title	domain	repo	status	owner	topic_slug	created	updated	related	state_hub_workstream_id
FIN-WP-0002	workplan	Client attribution and billing basis	financials	fin-hub	active	codex	financials	2026-08-10	2026-08-10	FIN-WP-0001 FIN-WP-0004 CUST-WP-0058	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

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

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

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

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

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

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.