Add client billing and cost evidence workplans

.custodian-brief.md

@@ -2,18 +2,20 @@
 # Custodian Brief — fin-hub
 
 **Domain:** financials  
-**Last synced:** 2026-08-09 19:40 UTC  
+**Last synced:** 2026-08-10 18:08 UTC  
 **State Hub:** http://127.0.0.1:8000 *(adjust if running on a remote machine)*
 
 ## Active Workstreams
 
-*(none — repo may need first-session setup)*
+### Client attribution and billing basis
+Progress: 1/6 done  |  workplan_id: `ebc1d2de-ae11-4cde-b860-047922fc74b9`
 
-## Inbox Hygiene
+**Open tasks:**
-
+- ! Add engagement revenue and margin reporting  `f917bb0b`
-**Stale unread:** 1 message(s) older than 3 day(s) — triage at session start.
+- ! Define shared-infrastructure allocation  `899a5c29`
-**Missing thread_id:** 1 unread message(s) lack supersession chains.
+- ! Export a per-client billing basis  `b5886131`
-- ! the-custodian: Client-billing gap assessment — proposed FIN-WP-0002 skeleton  `9c8e8ed4`
+- ! Select the external invoicing system  `d30b606f`
+- · Add client attribution  `904e9edc`
 
 ---
 ## MCP Orientation (when available)

SCOPE.md

@@ -5,11 +5,14 @@
 - Budget, commitment, burn rate, runway projection, and token spend models
 - Manual CSV import for cloud and API costs (v0.1)
 - Runway calculator with alert thresholds
+- Client-level cost attribution, engagement revenue and margin reporting, and
+  billing-basis exports for external bookkeeping/invoicing systems
 - FOS §9 cross-hub signals: fin→dev (budget pressure), fin→ops (cost attribution), fin→canon (viability alerts)
 - hub-core generic primitives (domains, repos, messages, progress)
 
 ## Out of Scope
 
-- Payment execution, invoicing, or banking integration
+- Legal invoice generation or numbering, bookkeeping, payment execution or
+  tracking, and banking integration
 - Tax filing or legal entity management
-- Multi-tenant customer billing (deferred to RaaS T26)
+- Authority for client identity or infrastructure resource identity

WORK-RECORDS.md

@@ -10,7 +10,9 @@
 | --- | --- | --- | --- | --- |
 | workplan | FIN-WP-0000 | finished | — | workplans/FIN-WP-0000-repo-integration.md |
 | workplan | FIN-WP-0001 | finished | — | workplans/FIN-WP-0001-runway-operations-lane.md |
-| workplan | FIN-WP-0002 | proposed | — | workplans/FIN-WP-0002-fabric-authority-boundary.md |
+| workplan | FIN-WP-0002 | active | — | workplans/FIN-WP-0002-client-attribution-and-billing-basis.md |
+| workplan | FIN-WP-0003 | proposed | — | workplans/FIN-WP-0003-fabric-authority-boundary.md |
+| workplan | FIN-WP-0004 | proposed | — | workplans/FIN-WP-0004-resource-cost-evidence-contract.md |
 | task | FIN-WP-0000-T01 | done | — | workplans/FIN-WP-0000-repo-integration.md |
 | task | FIN-WP-0000-T02 | done | — | workplans/FIN-WP-0000-repo-integration.md |
 | task | FIN-WP-0000-T03 | done | — | workplans/FIN-WP-0000-repo-integration.md |
@@ -21,6 +23,18 @@
 | task | FIN-WP-0001-T04 | done | — | workplans/FIN-WP-0001-runway-operations-lane.md |
 | task | FIN-WP-0001-T05 | done | — | workplans/FIN-WP-0001-runway-operations-lane.md |
 | task | FIN-WP-0001-T06 | done | — | workplans/FIN-WP-0001-runway-operations-lane.md |
-| task | FIN-WP-0002-T01 | todo | — | workplans/FIN-WP-0002-fabric-authority-boundary.md |
+| task | FIN-WP-0002-T00 | done | — | workplans/FIN-WP-0002-client-attribution-and-billing-basis.md |
-| task | FIN-WP-0002-T02 | todo | — | workplans/FIN-WP-0002-fabric-authority-boundary.md |
+| task | FIN-WP-0002-T01 | todo | — | workplans/FIN-WP-0002-client-attribution-and-billing-basis.md |
-| task | FIN-WP-0002-T03 | todo | — | workplans/FIN-WP-0002-fabric-authority-boundary.md |
+| task | FIN-WP-0002-T02 | wait | — | workplans/FIN-WP-0002-client-attribution-and-billing-basis.md |
+| task | FIN-WP-0002-T03 | wait | — | workplans/FIN-WP-0002-client-attribution-and-billing-basis.md |
+| task | FIN-WP-0002-T04 | wait | — | workplans/FIN-WP-0002-client-attribution-and-billing-basis.md |
+| task | FIN-WP-0002-T05 | wait | — | workplans/FIN-WP-0002-client-attribution-and-billing-basis.md |
+| task | FIN-WP-0003-T01 | todo | — | workplans/FIN-WP-0003-fabric-authority-boundary.md |
+| task | FIN-WP-0003-T02 | todo | — | workplans/FIN-WP-0003-fabric-authority-boundary.md |
+| task | FIN-WP-0003-T03 | todo | — | workplans/FIN-WP-0003-fabric-authority-boundary.md |
+| task | FIN-WP-0004-T01 | todo | — | workplans/FIN-WP-0004-resource-cost-evidence-contract.md |
+| task | FIN-WP-0004-T02 | todo | — | workplans/FIN-WP-0004-resource-cost-evidence-contract.md |
+| task | FIN-WP-0004-T03 | todo | — | workplans/FIN-WP-0004-resource-cost-evidence-contract.md |
+| task | FIN-WP-0004-T04 | todo | — | workplans/FIN-WP-0004-resource-cost-evidence-contract.md |
+| task | FIN-WP-0004-T05 | todo | — | workplans/FIN-WP-0004-resource-cost-evidence-contract.md |
+| task | FIN-WP-0004-T06 | todo | — | workplans/FIN-WP-0004-resource-cost-evidence-contract.md |

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

@@ -0,0 +1,160 @@
+---
+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: todo
+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.
+
+## Add engagement revenue and margin reporting
+
+```task
+id: FIN-WP-0002-T02
+status: wait
+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.
+
+## Define shared-infrastructure allocation
+
+```task
+id: FIN-WP-0002-T03
+status: wait
+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.

workplans/FIN-WP-0003-fabric-authority-boundary.md

@@ -15,6 +15,7 @@ related:
   - FIN-WP-0001
   - SHR-INV-0001
   - STATE-WP-0079
+state_hub_workstream_id: "1f6698f4-65b9-4e3b-bdf5-b079341e4581"
 ---
 
 # Fabric authority boundary for State Hub retirement
@@ -31,6 +32,7 @@ define any hub-core projection, and support State Hub fabric route disposition
 id: FIN-WP-0003-T01
 status: todo
 priority: high
+state_hub_task_id: "4471c006-5740-4241-8c81-251134c82f0d"
 ```
 
 Document which fabric entities/APIs are authoritative here vs State Hub read
@@ -42,6 +44,7 @@ models; publish consumer contract for migration.
 id: FIN-WP-0003-T02
 status: todo
 priority: high
+state_hub_task_id: "76c7ed79-8614-4e42-9e4c-f50bf789b584"
 ```
 
 With STATE-WP-0079, plan cutover for fabric ingest/read routes and dashboard
@@ -53,6 +56,7 @@ consumers; row-count and provenance checks.
 id: FIN-WP-0003-T03
 status: todo
 priority: low
+state_hub_task_id: "ae36e4e7-c39d-4027-bc49-e7abb52fb9e1"
 ```
 
 If orientation needs a hub-core projection, define port usage without copying

workplans/FIN-WP-0004-resource-cost-evidence-contract.md

@@ -0,0 +1,177 @@
+---
+id: FIN-WP-0004
+type: workplan
+title: "Establish the resource cost evidence contract"
+domain: infotech
+repo: fin-hub
+status: proposed
+owner: codex
+topic_slug: financials
+created: "2026-08-10"
+updated: "2026-08-10"
+related:
+  - FIN-WP-0001
+  - RESOURCE-WP-0002
+  - RESOURCE-WP-0003
+state_hub_workstream_id: "67b6de6c-4820-4478-9789-f50260204c27"
+---
+
+# FIN-WP-0004 — resource cost evidence contract
+
+## Goal
+
+Establish a versioned, provenance-bearing exchange between `fin-hub` and
+`resource-control` so booked financial facts can be joined to concrete
+infrastructure resources, technical utilization, forecasts, allocations, and
+optimization scenarios without creating competing ledgers.
+
+`fin-hub` remains authoritative for booked costs, credits, tax and currency
+treatment, budgets, financial commitments, burn, runway, and viability
+signals. `resource-control` remains authoritative for resource identity,
+lifecycle, demand and capacity forecasts, technical usage, allocation evidence,
+unit economics, and infrastructure optimization cases.
+
+This is a proposed companion to `RESOURCE-WP-0003` and should move to `ready`
+only after both repository owners review the authority matrix.
+
+## T01 — Review and record the authority boundary
+
+```task
+id: FIN-WP-0004-T01
+status: todo
+priority: high
+state_hub_task_id: "6616e6a0-b0f3-4b82-a081-083891e2fb6e"
+```
+
+Review existing fin-hub ledger, commitment, provider-import, service-cost,
+burn, and runway models against the revised `resource-control` intent. Record
+one authoritative writer for each exchanged concept and identify existing
+fields or reports that imply duplicate authority.
+
+Explicitly distinguish:
+
+- provider invoice or booked-cost evidence from analytical cost allocation;
+- financial commitments from technical commitment candidates;
+- budgets and viability constraints from demand forecasts;
+- resource-control actual-cost projections from fin-hub booked facts; and
+- internal showback evidence from customer billing.
+
+Done when the boundary is reviewed jointly with `RESOURCE-WP-0003-T02` and
+there is no ambiguous ownership of a ledger, forecast, allocation, or resource.
+
+## T02 — Specify fin-hub to resource-control booked-cost evidence
+
+```task
+id: FIN-WP-0004-T02
+status: todo
+priority: high
+state_hub_task_id: "0a90dd6f-b0c9-42dc-b625-cfedf0471143"
+```
+
+Define a stable export or projection for authoritative booked-cost evidence.
+It must cover source record identity, provider and account reference,
+accounting and service periods, currency, net/gross and tax semantics, credits
+or discounts, correction relationships, provenance, and available attribution
+keys.
+
+Support joins using the agreed subset of `resource_id`, `service_id`,
+`workload_id`, `tenant_id`, `environment`, and `cost_attribution_key` without
+requiring fin-hub to own the resource catalog. Unknown and unattributed values
+must remain explicit.
+
+Done when representative Host Europe or other provider rows can be exported
+idempotently and joined without copying invoice authority into
+`resource-control`.
+
+## T03 — Specify resource-control to fin-hub planning evidence
+
+```task
+id: FIN-WP-0004-T03
+status: todo
+priority: high
+state_hub_task_id: "ad9dccb4-85be-4f19-b36e-2f7165a879f5"
+```
+
+Define ingestion for resource references, allocation evidence, low/base/high
+demand and cost forecasts, internal and external labor assumptions, technical
+usage, commitment candidates, and optimization scenarios. Preserve forecast
+version, observation period, uncertainty, assumptions, and source provenance.
+
+Planning evidence must not be posted as booked spend. Define how an approved
+commitment candidate becomes a financial commitment and how superseded
+forecasts remain queryable for later variance analysis.
+
+Done when the PostgreSQL backup forecast can enter fin-hub without being
+mistaken for an invoice or actual expenditure.
+
+## T04 — Expose budgets, commitments, and viability constraints
+
+```task
+id: FIN-WP-0004-T04
+status: todo
+priority: medium
+state_hub_task_id: "3620fc2a-be3d-40aa-b357-d7741078c192"
+```
+
+Define the bounded financial signals that resource-control needs when ranking
+procurement and optimization options: applicable budget ceiling, active
+commitment state, burn or runway pressure, currency basis, effective period,
+and signal provenance.
+
+Do not export payment credentials, private invoice documents, or unrelated
+ledger detail. Consumers must be able to distinguish a policy constraint from
+an informational warning.
+
+Done when resource-control can evaluate affordability and commitment pressure
+without reproducing fin-hub's allocator or runway logic.
+
+## T05 — Implement and reconcile the first round trip
+
+```task
+id: FIN-WP-0004-T05
+status: todo
+priority: high
+state_hub_task_id: "9a411734-76f6-4c8d-9a48-b5a08cf8fd1f"
+```
+
+Implement the smallest interfaces needed for the `RESOURCE-WP-0002` backup
+case. Reconcile a forecast, an attributed booked-cost period, and a variance
+result across both repositories. Test duplicate delivery, corrections,
+unattributed cost, missing keys, currency semantics, and revised forecasts.
+
+Record row counts, totals, provenance, and ownership assertions on both sides.
+Do not make the integration depend on mutable prose or filename conventions.
+
+Done when the same cost is booked exactly once, projected to resource-control,
+joined to technical evidence, and returned as planning or variance evidence
+without becoming a second financial fact.
+
+## T06 — Generalize and operate the contract
+
+```task
+id: FIN-WP-0004-T06
+status: todo
+priority: medium
+state_hub_task_id: "a1309d51-32c3-4a9d-99f5-4dfb7abf4b3e"
+```
+
+Validate the contract with one non-storage resource and one shared service.
+Define versioning, compatibility, correction, reconciliation, data-quality,
+and review procedures. Add operator-facing visibility for rejected records,
+unattributed booked cost, stale forecasts, and reconciliation failures.
+
+Done when the contract supports storage, compute or cluster capacity, and a
+shared-service allocation without changing the authority boundary.
+
+## Acceptance
+
+- [ ] One reviewed authority matrix is linked from both repositories.
+- [ ] Booked financial facts remain authoritative only in fin-hub.
+- [ ] Resource identity and technical allocation remain authoritative only in
+      resource-control.
+- [ ] Forecasts cannot be confused with invoices or booked expenditure.
+- [ ] Exchange records carry stable identifiers, periods, provenance, and
+      correction semantics.
+- [ ] Backup completes a reconciled round trip with no double counting.
+- [ ] At least one non-storage and one shared-service case validate the
+      generalized contract.