the-custodian/docs/client-hub-scoping.md

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