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	finished	codex	financials	2026-08-10	2026-08-11	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: done
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.

Completed 2026-08-11: added a reporting-only allocation consumer for current resource-control AllocationEvidence. It requires uniquely claimed current financial facts, validates period/environment/currency and producer totals, retains the versioned method and provenance, and uses deterministic largest-remainder minor-unit rounding. Per-instance targets plus the explicit unattributed residual reconcile exactly to booked cost. Tests cover rounding, missing facts, mismatches, evidence revisions, and duplicate allocation.

Export a per-client billing basis

id: FIN-WP-0002-T04
status: done
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.

Completed 2026-08-11: added a deterministic v0.1 billing-basis artifact and ledger billing-basis command. Each client-period record contains the current price/revision, direct and allocated cost, margin, financial-fact/correction IDs, allocation/revision IDs, and non-secret provenance. Stable IDs change only when an input basis changes. Residuals, non-client targets, and missing prices are explicit exceptions. The artifact carries a mandatory reporting- only disclaimer and has no invoice, bookkeeping, or payment behavior.

Select the external invoicing system

id: FIN-WP-0002-T05
status: done
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.

Completed 2026-08-11: the operator selected DATEV Unternehmen online as the authoritative external GoBD bookkeeping and document-retention system. Qonto is the preferred complementary invoice workflow and managed DATEV transport when DUO lacks or does not conveniently expose a required function. Added a provider-neutral, capability-declared adapter contract with DATEV as the default, explicit Qonto selection, exact input-schema compatibility, and fail-closed migrations. The adapters create incomplete, side-effect-free handoff drafts only; legal/tax completion, issuance, delivery, payments, and bookkeeping remain authorized external actions. The integration, custody, retention, and upgrade controls are recorded in docs/accounting-adapter-boundary.md. Live provider activation is tracked by FIN-WP-0005.

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.