docs(adr-0057): addendum — org-structure surfacing & edition tiering

[xuyushun441-sys]

What

Appends an addendum to ADR-0057 settling how the three org-shaped objects are surfaced in the Setup app and tiered across editions — a gap ADR-0057 left open (it settled the authorization model, not the UI surfacing). Docs-only, no behaviour change.

Why

sys_organization (tenant), sys_business_unit (partition tree), and sys_team (flat collaboration) currently land flat in the Setup group_people_org menu and read as three competing "organisation" concepts — worst in single-tenant, where sys_organization is a single un-creatable row.

Decisions (D9–D12)

• D9 — Edition tiering:floor=teams (all editions) / ceiling=BU (enterprise) / tenant=org (multi-org only). Teams is the auth-native flat primitive with no structural substitute; BU's distinguishing rollup is paid; the tenant container is degenerate in single-tenant.
• D10 — Nav surfacing follows the capability (ADR-0029 K2); objects stay registered open. Move nav_business_units to the hierarchy-security capability (today's requiresObject gate is inert — the object is registered unconditionally); gate nav_organizations/nav_invitations on multiOrgEnabled. Flags that NavigationItem needs a visible/requiresFeature predicate first (ADR-0049: gated or not claimed).
• D11 — Drop team from sys_business_unit.kind (0 repo usages, no migration) — removes the head-on collision with the first-class sys_team.
• D12 — Add denormalised sys_user.primary_business_unit_id (mirrors manager_id, feat(platform-objects): add sys_user.manager_id to back the own_and_reports scope (ADR-0057) #2133), maintained from sys_business_unit_member.is_primary, so "pick people by BU" becomes a config-only lookupFilters filter with zero query-engine change (lookups filter only target-object fields; the junction can't be traversed in one filter today).

Plus: a forward note on feat/slim-remove-multitenant-runtime compatibility (why the multiOrgEnabled gate is kept), surfacing-conformance proofs (extends D8), and phasing PS-1/2/3.

Scope

Documentation only. Implementation lands in follow-up PRs (PS-1: D11 + org gate; PS-2: BU nav relocation; PS-3: primary_business_unit_id).

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
spec	Ready	Preview, Comment	Jun 21, 2026 3:44pm