diff --git a/.custodian-brief.md b/.custodian-brief.md index b7406b2..f23d6c7 100644 --- a/.custodian-brief.md +++ b/.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 - -**Stale unread:** 1 message(s) older than 3 day(s) — triage at session start. -**Missing thread_id:** 1 unread message(s) lack supersession chains. -- ! the-custodian: Client-billing gap assessment — proposed FIN-WP-0002 skeleton `9c8e8ed4` +**Open tasks:** +- ! Add engagement revenue and margin reporting `f917bb0b` +- ! Define shared-infrastructure allocation `899a5c29` +- ! Export a per-client billing basis `b5886131` +- ! Select the external invoicing system `d30b606f` +- · Add client attribution `904e9edc` --- ## MCP Orientation (when available) diff --git a/SCOPE.md b/SCOPE.md index 36b4c56..679c8e5 100644 --- a/SCOPE.md +++ b/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) \ No newline at end of file +- Authority for client identity or infrastructure resource identity diff --git a/WORK-RECORDS.md b/WORK-RECORDS.md index f025bd1..55b8983 100644 --- a/WORK-RECORDS.md +++ b/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-T02 | todo | — | workplans/FIN-WP-0002-fabric-authority-boundary.md | -| task | FIN-WP-0002-T03 | 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-T01 | todo | — | workplans/FIN-WP-0002-client-attribution-and-billing-basis.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 | diff --git a/workplans/FIN-WP-0002-client-attribution-and-billing-basis.md b/workplans/FIN-WP-0002-client-attribution-and-billing-basis.md new file mode 100644 index 0000000..7de8e8c --- /dev/null +++ b/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. diff --git a/workplans/FIN-WP-0003-fabric-authority-boundary.md b/workplans/FIN-WP-0003-fabric-authority-boundary.md index 8032b90..308a1e3 100644 --- a/workplans/FIN-WP-0003-fabric-authority-boundary.md +++ b/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 diff --git a/workplans/FIN-WP-0004-resource-cost-evidence-contract.md b/workplans/FIN-WP-0004-resource-cost-evidence-contract.md new file mode 100644 index 0000000..08f2711 --- /dev/null +++ b/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.