# 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).