Client tenancy and hierarchy

Status and scope

Field	State
Contract status	Current master
Implementation status	Mixed; current migrations/source define shipped schema
Last source review	2026-08-26
Runtime verification	Required for deployed grants, bindings, and isolation
Owner	Not recorded in this public document

This master replaces the client-hierarchy design, Phase 1b brands/user-client specification, and hierarchy rebuild plan. Current migrations/source remain authoritative for shipped schema.

Canonical model

Client (tenant)
 ├── Brands
 ├── Users and role/client assignments
 └── Platform account bindings
      └── Campaign → Ad set → Ad → Creative

• Supabase clients.id is the relational key; clients.slug is ClickHouse client_id.
• Brands group accounts/reporting beneath a client; they do not replace tenant scope.
• Connector secrets resolve through credential_ref, not inline columns.
• Account bindings use canonical platform/account identity and must not duplicate across tenants.

Scope and access

• Browser filters never grant access.
• User-facing server entrypoints resolve allowed client scope.
• Tenant-locked users remain locked when another slug is supplied.
• RBAC comes from current definitions, not route visibility.
• New tables and mutations require explicit tenant/RLS review.

Change contract

Schema/hierarchy changes update migrations, row/query types, tenant filters, binding/credential resolution, admin surfaces, isolation/reporting tests, onboarding, and data-model documentation together.

Acceptance gates

• allowed, forbidden, missing, and multi-client callers are tested;
• clients.slug ↔ analytics client_id is verified;
• accounts cannot silently resolve to the wrong tenant;
• brand/account grouping does not change totals;
• reassignment invalidates related query state;
• production is not claimed from migration/build success alone.

Provenance

Replaced document	Contribution retained here
Client hierarchy design	Original audit and target hierarchy
Phase 1b brands + client scoping	Brands schema, user↔client model, tenant rules
Client → brand → account plan	Execution gaps, binding model, verification order