CUST-WP-0058: T04 approved, T05 client-hub scoping, T06 fin-hub gap done
Service contract v0.1 accepted (Bernd 2026-07-10). Client-hub scoped as core-hub extension (client/engagement/app_instance/support_state, CLNT-WP skeleton). fin-hub gap assessment: 5 gaps, FIN-WP-0002 skeleton posted to fin-hub lane (msg 9c8e8ed4); recommendation fin-hub stays reporting-only. Remaining: T07 delivery-lane pilot, T08 closeout. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
codex
parent
e9cded96fc
commit
e61c7ed15c
4 changed files with 142 additions and 6 deletions
|
|
@ -1,8 +1,8 @@
|
|||
---
|
||||
title: Business-App Service Contract
|
||||
version: v0.1
|
||||
status: proposal
|
||||
review: pending — requires Bernd's approval before normative use
|
||||
status: accepted
|
||||
review: approved by Bernd 2026-07-10
|
||||
created: "2026-07-10"
|
||||
workplan: CUST-WP-0058
|
||||
task: CUST-WP-0058-T04
|
||||
|
|
|
|||
83
docs/client-hub-scoping.md
Normal file
83
docs/client-hub-scoping.md
Normal file
|
|
@ -0,0 +1,83 @@
|
|||
# Client-Hub Scoping — the Client/Commercial Management Plane
|
||||
|
||||
**Created:** 2026-07-10
|
||||
**Workplan:** `CUST-WP-0058-T05`
|
||||
**Decisions applied:** DR-1 C (instance-per-client, consolidation-aware),
|
||||
DR-2 B (Binky Hedgehog GmbH as client #1), DR-3 A (app-local identity)
|
||||
**Contract:** `canon/standards/business-app-service-contract_v0.1.md` (§7)
|
||||
|
||||
## Why a fourth plane
|
||||
|
||||
The hub ecosystem manages dev (state-hub), ops (ops-hub), and fin (fin-hub)
|
||||
concerns. Commercial operation of business apps adds concerns none of those
|
||||
own: who the clients are, what they are entitled to, which instances serve
|
||||
them, and what support/SLA state applies. Encoding any of this in the apps
|
||||
themselves is prohibited by the service contract (§7.2).
|
||||
|
||||
## Shape decision: core-hub extension
|
||||
|
||||
**Client-hub is a Core Hub extension (ops-hub pattern), not a standalone
|
||||
runtime.** Justification against the alternatives:
|
||||
|
||||
- *Standalone service*: adds an operational surface (deploy, backup, monitor)
|
||||
for what is initially a small registry; contradicts the "don't spawn a
|
||||
runtime per aspect" guard from the hub-ecosystem review.
|
||||
- *fin-hub extension*: client identity is not a financial concern; billing
|
||||
*references* clients but does not own them.
|
||||
- *state-hub tables*: state-hub is the internal dev plane and must stay out
|
||||
of anything client-related (dev plane never in the client dependency graph).
|
||||
|
||||
Core Hub is the production framework (`hub.coulomb.social`), already runs the
|
||||
ops-hub extension, and hub-core primitives (domains/repos/messages/progress
|
||||
router factories, JSON context seams) are available for reuse where they fit.
|
||||
|
||||
## Entity model (v1)
|
||||
|
||||
| Entity | Purpose | Key fields (sketch) |
|
||||
| --- | --- | --- |
|
||||
| `client` | Business client registry; **Binky Hedgehog GmbH is client #1** | name, legal form, contacts, status (prospect/active/offboarding/closed) |
|
||||
| `engagement` | Contract/entitlement envelope per client×app | client_id, app slug, entitlements (JSON), contract refs (pointer, no documents), start/end |
|
||||
| `app_instance` | Client↔instance mapping (1..n per client, DR-1) | client_id, engagement_id, app slug, environment ref (ops-hub), cost attribution key (fin-hub §5.1), consolidation state (dedicated/consolidated) |
|
||||
| `support_state` | SLA/support posture per engagement | tier, contacts, escalation path, open-issue pointer (issue-core) |
|
||||
|
||||
Relations to other planes are **references, not ownership**: `app_instance`
|
||||
points at ops-hub environment/service records and carries the fin-hub cost
|
||||
key; documents/contracts stay in their own custody (no file storage here).
|
||||
|
||||
## Boundaries (out of scope)
|
||||
|
||||
- Payment, invoicing, dunning — fin-hub boundary question (T06)
|
||||
- Contract document storage or legal authority — human/Binky Hedgehog custody
|
||||
- Client *user* accounts — app-local per DR-3; client-hub tracks the client
|
||||
organization, never its end users
|
||||
- Task/issue lifecycle — issue-core owns; support_state only points
|
||||
|
||||
## Consolidation-awareness (DR-1 C)
|
||||
|
||||
`app_instance.consolidation_state` plus the tenant key make the early
|
||||
cost-optimization move a data operation: consolidating N instances updates N
|
||||
rows (dedicated→consolidated onto shared infra) without model changes.
|
||||
Consolidation events must emit a signal that the DR-3 identity trigger can
|
||||
observe.
|
||||
|
||||
## Proposed workplan skeleton (for `/home/worsch/core-hub` or a `client-hub` extension repo)
|
||||
|
||||
```
|
||||
CLNT-WP-0001 — client-hub extension bootstrap
|
||||
T01 Extension scaffold following ops-hub repo pattern (todo, high)
|
||||
T02 client + engagement models, migrations, /api/v2 routes (todo, high)
|
||||
T03 app_instance model with ops-hub env ref + fin-hub cost key (todo, high)
|
||||
T04 support_state model + issue-core pointer (todo, medium)
|
||||
T05 Seed client #1 (Binky Hedgehog GmbH) + vergabe-teilnahme pilot
|
||||
engagement/instance rows (todo, medium)
|
||||
T06 Operator console views (clients, engagements, instances) (todo, low)
|
||||
```
|
||||
|
||||
Ownership question for Bernd at pickup: separate `client-hub` repo (like
|
||||
`ops-hub`) or a module inside `core-hub`? Recommendation: **separate repo**,
|
||||
consistent with the established extension pattern and repo-boundary rules.
|
||||
|
||||
## Pickup
|
||||
|
||||
Registered as an ecosystem todo when CUST-WP-0058-T08 closes; implementation
|
||||
does not start inside the-custodian (repo-boundary).
|
||||
53
docs/fin-hub-client-billing-gap.md
Normal file
53
docs/fin-hub-client-billing-gap.md
Normal file
|
|
@ -0,0 +1,53 @@
|
|||
# fin-hub Client-Billing Gap Assessment
|
||||
|
||||
**Created:** 2026-07-10
|
||||
**Workplan:** `CUST-WP-0058-T06`
|
||||
**Baseline reviewed:** `FIN-WP-0000/0001` (finished) — models `budget.py`,
|
||||
`service_cost.py`; HostEurope CSV ingest; runway calculator; fin→ops coupling.
|
||||
**Contract obligations:** business-app service contract §5 (cost attribution
|
||||
key `client × app × instance`, per-instance cost reporting).
|
||||
|
||||
## What exists
|
||||
|
||||
- `ServiceCost`: per-service infra cost, keyed `service_id × environment ×
|
||||
period_month` (EUR, source-tagged) — fin→ops attribution works.
|
||||
- Budgets, commitments, runway projection with alert thresholds.
|
||||
- Manual CSV ingest (HostEurope) as designed for v0.1.
|
||||
|
||||
## Gaps vs. commercial operation
|
||||
|
||||
| # | Gap | Detail | Severity |
|
||||
| --- | --- | --- | --- |
|
||||
| G1 | **No client dimension** | `ServiceCost` cannot express `client × app × instance` (§5.1). Instance-per-client (DR-1 C) makes this the primary reporting axis. | high |
|
||||
| G2 | **No revenue side** | Costs and budgets only; engagement pricing is not recorded, so margin-per-client — the input to DR-1's cost-optimization decision — cannot be computed. | high |
|
||||
| G3 | **No per-instance cost split** | HostEurope CSV gives host-level cost; client instances share cluster nodes. An allocation method (namespace/resource-based split) is needed for §5.2. | medium |
|
||||
| G4 | **Invoicing boundary undecided** | fin-hub SCOPE excludes payment/invoicing. Something must own invoice generation for clients. | medium |
|
||||
| G5 | **No client-hub reference seam** | Once client-hub exists, cost rows should reference its `app_instance` / cost key instead of free-form strings. | low (sequencing) |
|
||||
|
||||
## Boundary recommendation (G4)
|
||||
|
||||
Keep fin-hub **reporting-only**: it owns attribution, margin, and runway; an
|
||||
external bookkeeping/invoicing system (e.g. lexoffice/sevDesk — Bernd's
|
||||
choice, GoBD-relevant) owns invoice generation and payment tracking. fin-hub
|
||||
provides the per-engagement billing basis (attributed cost + entitlement
|
||||
price) as an export, never executes payments. This keeps constitution §4
|
||||
financial custody with the human/GmbH.
|
||||
|
||||
## Proposed workplan skeleton (for `/home/worsch/fin-hub`)
|
||||
|
||||
```
|
||||
FIN-WP-0002 — client attribution and billing basis
|
||||
T01 Add client attribution: cost rows carry client/app/instance key
|
||||
(string key now; client-hub FK seam later, G5) (todo, high)
|
||||
T02 Engagement revenue model: price per engagement period, margin view
|
||||
per client × app (todo, high)
|
||||
T03 Per-instance allocation method for shared infra (namespace-based
|
||||
split; documented assumptions) (todo, medium)
|
||||
T04 Billing-basis export per client × period (feeds external invoicing;
|
||||
no payment execution) (todo, medium)
|
||||
T05 Decision + doc: external invoicing system selection (human gate,
|
||||
GoBD) (wait, high)
|
||||
```
|
||||
|
||||
Posted to the fin-hub lane via State Hub message; implementation belongs in
|
||||
the fin-hub repo (ADR-001 — the workplan file originates there).
|
||||
|
|
@ -101,7 +101,7 @@ for T04: app-local accounts, consolidation-ready.
|
|||
|
||||
```task
|
||||
id: CUST-WP-0058-T04
|
||||
status: progress
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "a3cec70c-04a1-42a9-a6b0-3d2943b73968"
|
||||
```
|
||||
|
|
@ -121,7 +121,7 @@ the reference implementation. Unblocked: DR-1/DR-3 resolved 2026-07-10.
|
|||
|
||||
```task
|
||||
id: CUST-WP-0058-T05
|
||||
status: todo
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "442b7f81-44c7-4301-9466-c99c240c4e49"
|
||||
```
|
||||
|
|
@ -138,7 +138,7 @@ skeleton for the owning repo, not implementation. Unblocked: DR-1 resolved.
|
|||
|
||||
```task
|
||||
id: CUST-WP-0058-T06
|
||||
status: todo
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "3a63f122-2398-4149-8458-eb5a3a54627c"
|
||||
```
|
||||
|
|
@ -153,7 +153,7 @@ FIN-WP workplan skeleton posted to the fin-hub lane.
|
|||
|
||||
```task
|
||||
id: CUST-WP-0058-T07
|
||||
status: wait
|
||||
status: todo
|
||||
priority: high
|
||||
state_hub_task_id: "d07443ab-76b1-4d66-981c-e83fcb915c0d"
|
||||
```
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue