Skip to content

SA Member Hierarchy and Manager Operations

Purpose

This document defines the current v1 invariants for SA-local membership hierarchy, sa_manager, and the core member-management operations that must preserve SA integrity.

Read this document as the V1 layer in the progressive SA design.

It refines the V0 SA setup and stamping model by adding member hierarchy, child-SA hierarchy, and the resulting roll-up logic for managerial and regional views.

For the intended progression of V0 → V1 → V2, see SA Design Refinement Layers.

It is intentionally parallel to the SA construction decisions recorded in ADR 0001.

Terminology in this document follows the repo definitions in Terminology, especially Serviced Account (SA), actor, membership, and sa_manager.

1. Core Modeling Position

sa_manager is not a different membership type.

It is the current root member of the membership tree for one SA.

The difference between sa_manager and other members is scope, not object class:

  • any member may own customers
  • any member may have subordinates
  • any member with subordinates may roll up team metrics inside the current SA
  • only the current sa_manager gets SA-level roll-up from the current SA through all descendant child-SAs

2. Two Tree Structures

The model depends on two separate tree structures.

2.1 SA Tree

  • SA_ROOT is the system root SA
  • each SA<x> is a proper SA under SA_ROOT
  • each SA has at most one parent SA
  • child-SA roll-up is recursive downward from the current SA

2.2 Membership Tree

Within one SA:

  • the membership hierarchy is a tree
  • the current sa_manager is the unique root member of that tree
  • every non-sa_manager member must have exactly one manager in the same SA
  • any member may have zero or more direct subordinates
  • no circular reporting is allowed

The manager link is modeled as a self-reference on membership.

Current invariant:

  • only the current sa_manager may have manager_member_id = NULL
  • every other member must have a non-null manager in the same SA
  • the member with manager_member_id = NULL must be the same member referenced by SA.sa_manager

This means the membership tree always has exactly one root.

4. Roll-Up Rules

4.1 Member-Level Roll-Up

Any member with subordinates may roll up metrics from:

  • self
  • all subordinate members recursively

This is the member-level expansion:

  • actor -> extended_actor

where:

  • extended_actor = actor + all subordinate members recursively

4.2 SA-Level Roll-Up

The current sa_manager of an SA may also roll up metrics from:

  • the current SA
  • all descendant child-SAs recursively

This is the SA-level expansion:

  • sa -> extended_sa

where:

  • extended_sa = current SA + all descendant child-SAs recursively

5. Manager Change Invariants

Changing sa_manager is an invariant-sensitive operation.

5.1 Atomicity

  • manager change must be atomic
  • no persisted intermediate state may have:
  • zero membership-tree roots
  • multiple membership-tree roots
  • broken manager links that violate the tree invariant

5.2 Incoming Manager Eligibility

  • the incoming manager must first be added as a member of the same SA
  • promotion is a second step after membership exists

5.3 Outgoing Manager Reattachment

When sa_manager changes:

  • the outgoing sa_manager immediately becomes a direct subordinate of the new sa_manager

This is both a structural invariant and the expected business handover pattern.

5.4 Incoming Manager Existing Team

If an existing member is promoted to sa_manager:

  • that member must first use Release Team
  • the released team rolls up to that member's current manager

This avoids circular or ambiguous reporting during promotion.

6. Member Operations

6.1 Add Member

  • a new member is added inside one SA
  • the default manager is the current sa_manager
  • later reassignment may happen separately

This keeps member creation simple and avoids forcing the admin to make organizational decisions during intake.

6.2 Remove Member

Removal is strictly blocked unless the member has:

  • no subordinates
  • no customers

There must be no orphaned team members and no orphaned customers.

7. Team and Customer Reassignment Operations

Use reader-facing imperative labels in this document. Implementation-facing identifiers may use the snake_case forms defined in Terminology.

7.1 Release Team

Release Team always means complete release.

It moves all direct subordinates of a member to that member's current manager.

Partial movement is not Release Team; it is reassignment.

7.2 Reassign Team Member

Reassign Team Member allows one explicitly selected subordinate member to be reassigned to one explicitly selected manager.

Rules:

  • reassignment must stay within the same SA
  • the assignee manager is chosen explicitly
  • the operation must reject any circular reporting outcome

7.3 Release Customers

Release Customers always means complete release.

It moves all directly owned customers of a member to that member's current manager.

Partial movement is not Release Customers; it is customer reassignment.

7.4 Reassign Customer

Reassign Customer allows one explicitly selected customer to be reassigned individually.

Rules:

  • reassignment must stay within the same SA
  • the assignee member is chosen explicitly

8. Customer Ownership During Manager Change

Manager change does not automatically require customer reassignment when the outgoing manager remains a member of the SA.

Working rule:

  • if the outgoing manager remains in the SA, customers may remain with that member
  • if the outgoing manager leaves the SA, customer reassignment must follow the strict Remove Member rule

9. Cross-SA Isolation

Each SA is a separate governance domain.

Therefore:

  • manager links are SA-local
  • customer ownership is SA-local
  • roll-up logic is SA-local unless explicitly expanded through the child-SA tree
  • no manager, team, or customer inference crosses SA boundaries just because the same res.partner appears in another SA

10. Implementation Guidance

Any admin panel or service layer that changes membership structure must preserve these invariants at transaction boundaries.

At minimum the implementation must reject:

  • direct or indirect circular reporting
  • manager removal when subordinates still exist
  • member removal when customers still exist
  • promotion that leaves the tree with more than one root
  • promotion that leaves the tree with no root
  • reassignment across SA boundaries

11. Deferred

This document does not yet define:

  • exact database-field names beyond the current conceptual names
  • audit-log structure for hierarchy changes
  • approval workflow around manager-change requests
  • UI sequencing for the SA Admin Panel