@codingfactory/socialkit-vue 0.1.0 → 0.3.0

package/src/stores/circles.ts

@@ -0,0 +1,2114 @@
+/**
+ * Generic circles store factory for SocialKit-powered frontends.
+ */
+
+import { defineStore } from 'pinia'
+import type {
+  Circle,
+  CircleActorContext,
+  CircleAutomodRule,
+  CircleAutomodRuleInput,
+  CircleBanRecord,
+  CircleCreateInput,
+  CircleFilters,
+  CircleInviteLinkOptions,
+  CircleManagementBootstrap,
+  CircleManagementSection,
+  CircleMember,
+  CircleMemberRoleAssignmentResult,
+  CircleModerationAuditLogEntry,
+  CircleModerationReport,
+  CircleMuteMemberOptions,
+  CircleMuteRecord,
+  CircleReportDecision,
+  CircleRole,
+  CircleRoleDefinition,
+  CircleRoleDefinitionInput,
+  CircleRoleDefinitionUpdateInput,
+  CircleUpdateInput,
+  CirclesServiceInstance,
+  InviteLink,
+  JoinRequest,
+} from '../services/circles.js'
+
+interface CursorPaginationState {
+  cursor: string | null
+  hasMore: boolean
+}
+
+type ManagementCollectionKey =
+  | 'members'
+  | 'requests'
+  | 'roles'
+  | 'reports'
+  | 'bans'
+  | 'mutes'
+  | 'audit'
+  | 'automod'
+
+interface ManagementSectionLoadingState {
+  members?: boolean
+  requests?: boolean
+  roles?: boolean
+  reports?: boolean
+  bans?: boolean
+  mutes?: boolean
+  audit?: boolean
+  automod?: boolean
+}
+
+interface ManagementSectionErrorState {
+  members?: string | null
+  requests?: string | null
+  roles?: string | null
+  reports?: string | null
+  bans?: string | null
+  mutes?: string | null
+  audit?: string | null
+  automod?: string | null
+}
+
+interface CircleRoleAssignment {
+  id: string
+  user_id: string
+  role: CircleRole
+  assigned_at: string | null
+  user?: CircleMember['user']
+}
+
+interface CircleManagementCounts {
+  [key: string]: number
+  members: number
+  requests_pending: number
+  reports_pending: number
+  roles: number
+  bans_active: number
+  mutes_active: number
+}
+
+interface CircleManagementPermissionCatalogEntry {
+  key: string
+  label: string
+  description: string
+  module: string
+  owner_only: boolean
+  surfaced: boolean
+  section: string
+}
+
+type CircleMemberState = CircleMember
+
+interface CircleRoleStoreService {
+  fetchRoleDefinitions(circleId: string, cursor?: string | null): Promise<unknown>
+  listRoleDefinitions(circleId: string, cursor?: string | null): Promise<unknown>
+  listRoles(circleId: string, cursor?: string | null): Promise<unknown>
+  createRoleDefinition(circleId: string, input: CircleRoleDefinitionInput): Promise<unknown>
+  createRole(circleId: string, input: CircleRoleDefinitionInput): Promise<unknown>
+  updateRoleDefinition(circleId: string, roleId: string, input: CircleRoleDefinitionUpdateInput): Promise<unknown>
+  updateRole(circleId: string, roleId: string, input: CircleRoleDefinitionUpdateInput): Promise<unknown>
+  replaceRoleDefinitionPermissions(circleId: string, roleId: string, permissions: string[]): Promise<unknown>
+  replaceRolePermissions(circleId: string, roleId: string, permissions: string[]): Promise<unknown>
+  archiveRoleDefinition(circleId: string, roleId: string): Promise<void>
+  archiveRole(circleId: string, roleId: string): Promise<void>
+  assignMemberRoles(circleId: string, userId: string, roleIds: string[]): Promise<unknown>
+  removeMemberRole(circleId: string, userId: string, roleId: string): Promise<void>
+}
+
+export interface CirclesStoreConfig {
+  storeId?: string
+  circlesService: CirclesServiceInstance
+  getErrorMessage: (error: unknown) => string
+  persist?: Record<string, unknown>
+}
+
+const DEFAULT_FILTER_KEY = 'all'
+const DEFAULT_MANAGEMENT_COUNTS: CircleManagementCounts = {
+  members: 0,
+  requests_pending: 0,
+  reports_pending: 0,
+  roles: 0,
+  bans_active: 0,
+  mutes_active: 0,
+}
+
+const defaultPaginationState = (): CursorPaginationState => ({
+  cursor: null,
+  hasMore: true,
+})
+
+const emptyPaginationState = (): CursorPaginationState => ({
+  cursor: null,
+  hasMore: false,
+})
+
+const toCursorPaginationState = (response: {
+  meta?: {
+    pagination?: {
+      next_cursor?: string | null
+      has_more?: boolean
+    }
+  }
+}): CursorPaginationState => ({
+  cursor: response.meta?.pagination?.next_cursor ?? null,
+  hasMore: response.meta?.pagination?.has_more ?? Boolean(response.meta?.pagination?.next_cursor),
+})
+
+const normalizeFilters = (filters: CircleFilters): CircleFilters => {
+  const normalized: CircleFilters = {}
+
+  if (typeof filters.visibility === 'string' && filters.visibility.length > 0) {
+    normalized.visibility = filters.visibility
+  }
+
+  if (typeof filters.membership === 'string' && filters.membership.length > 0) {
+    normalized.membership = filters.membership
+  }
+
+  if (typeof filters.search === 'string') {
+    const search = filters.search.trim()
+    if (search.length > 0) {
+      normalized.search = search
+    }
+  }
+
+  return normalized
+}
+
+const buildFilterKey = (filters: CircleFilters): string => {
+  const normalized = normalizeFilters(filters)
+  const entries = Object.entries(normalized)
+    .sort(([leftKey], [rightKey]) => leftKey.localeCompare(rightKey))
+
+  if (entries.length === 0) {
+    return DEFAULT_FILTER_KEY
+  }
+
+  return entries.map(([key, value]) => `${key}:${value}`).join('|')
+}
+
+const mergeUniqueCircles = (existing: Circle[], incoming: Circle[]): Circle[] => {
+  const existingIds = new Set(existing.map(circle => circle.id))
+  const merged = [...existing]
+
+  for (const circle of incoming) {
+    if (existingIds.has(circle.id)) {
+      continue
+    }
+
+    existingIds.add(circle.id)
+    merged.push(circle)
+  }
+
+  return merged
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> => {
+  return typeof value === 'object' && value !== null
+}
+
+const readRecord = (value: unknown, key: string): Record<string, unknown> | null => {
+  if (!isRecord(value)) {
+    return null
+  }
+
+  const entry = value[key]
+  return isRecord(entry) ? entry : null
+}
+
+const readString = (value: unknown): string | null => {
+  return typeof value === 'string' && value.trim().length > 0 ? value.trim() : null
+}
+
+const readNullableString = (value: unknown): string | null => {
+  if (value === null || value === undefined) {
+    return null
+  }
+
+  return readString(value)
+}
+
+const readBoolean = (value: unknown): boolean | null => {
+  return typeof value === 'boolean' ? value : null
+}
+
+const readNumber = (value: unknown): number | null => {
+  return typeof value === 'number' && Number.isFinite(value) ? value : null
+}
+
+const isCircleVisibility = (value: unknown): value is Circle['visibility'] => {
+  return value === 'public' || value === 'closed' || value === 'secret'
+}
+
+const isCircleEntry = (value: unknown): value is Circle => {
+  if (!isRecord(value)) {
+    return false
+  }
+
+  return typeof value.id === 'string'
+    && value.id.length > 0
+    && typeof value.name === 'string'
+    && value.name.length > 0
+    && isCircleVisibility(value.visibility)
+}
+
+const sanitizeCirclesPayload = (payload: unknown): Circle[] => {
+  if (!Array.isArray(payload)) {
+    return []
+  }
+
+  return payload.filter(isCircleEntry)
+}
+
+const sanitizeCircleCollection = (circles: Circle[]): Circle[] => {
+  return sanitizeCirclesPayload(circles)
+}
+
+const sanitizePermissionKeys = (value: unknown): string[] => {
+  if (!Array.isArray(value)) {
+    return []
+  }
+
+  return value.filter((entry): entry is string => typeof entry === 'string' && entry.trim().length > 0)
+}
+
+const normalizeRoleDefinition = (value: unknown): CircleRoleDefinition | null => {
+  if (!isRecord(value)) {
+    return null
+  }
+
+  const id = readString(value.id)
+  const slug = readString(value.slug)
+  const name = readString(value.name)
+
+  if (id === null || slug === null || name === null) {
+    return null
+  }
+
+  return {
+    id,
+    slug,
+    name,
+    description: readNullableString(value.description),
+    color: readNullableString(value.color),
+    is_system: readBoolean(value.is_system) ?? false,
+    is_assignable: readBoolean(value.is_assignable) ?? true,
+    member_count: readNumber(value.member_count) ?? 0,
+    permissions: sanitizePermissionKeys(value.permissions),
+  }
+}
+
+const sanitizeRoleDefinitions = (value: unknown): CircleRoleDefinition[] => {
+  if (!Array.isArray(value)) {
+    return []
+  }
+
+  return value
+    .map((entry) => normalizeRoleDefinition(entry))
+    .filter((entry): entry is CircleRoleDefinition => entry !== null)
+}
+
+const normalizePermissionCatalogEntry = (value: unknown): CircleManagementPermissionCatalogEntry | null => {
+  if (!isRecord(value)) {
+    return null
+  }
+
+  const key = readString(value.key)
+  const label = readString(value.label)
+  const description = readString(value.description)
+  const module = readString(value.module)
+  const section = readString(value.section)
+
+  if (key === null || label === null || description === null || module === null || section === null) {
+    return null
+  }
+
+  return {
+    key,
+    label,
+    description,
+    module,
+    owner_only: readBoolean(value.owner_only) ?? false,
+    surfaced: readBoolean(value.surfaced) ?? false,
+    section,
+  }
+}
+
+const sanitizePermissionCatalog = (value: unknown): CircleManagementPermissionCatalogEntry[] => {
+  if (!Array.isArray(value)) {
+    return []
+  }
+
+  return value
+    .map((entry) => normalizePermissionCatalogEntry(entry))
+    .filter((entry): entry is CircleManagementPermissionCatalogEntry => entry !== null)
+}
+
+const sanitizeManagementCounts = (value: unknown): CircleManagementCounts => {
+  const counts: CircleManagementCounts = { ...DEFAULT_MANAGEMENT_COUNTS }
+
+  if (!isRecord(value)) {
+    return counts
+  }
+
+  for (const [key, entry] of Object.entries(value)) {
+    const numericValue = readNumber(entry)
+    if (numericValue !== null) {
+      counts[key] = numericValue
+    }
+  }
+
+  return counts
+}
+
+const extractItems = (value: unknown): unknown[] => {
+  if (Array.isArray(value)) {
+    return value
+  }
+
+  if (!isRecord(value)) {
+    return []
+  }
+
+  const data = readRecord(value, 'data')
+  const dataItems = data?.items
+  if (Array.isArray(dataItems)) {
+    return dataItems
+  }
+
+  const rootItems = value.items
+  if (Array.isArray(rootItems)) {
+    return rootItems
+  }
+
+  const rootData = value.data
+  if (Array.isArray(rootData)) {
+    return rootData
+  }
+
+  return []
+}
+
+const toUnknownCursorPaginationState = (value: unknown): CursorPaginationState => {
+  if (!isRecord(value)) {
+    return emptyPaginationState()
+  }
+
+  const meta = readRecord(value, 'meta')
+  const pagination = readRecord(meta, 'pagination')
+  const nextCursor = readNullableString(pagination?.next_cursor)
+
+  return {
+    cursor: nextCursor,
+    hasMore: readBoolean(pagination?.has_more) ?? (nextCursor !== null),
+  }
+}
+
+const extractRoleDefinitions = (value: unknown): CircleRoleDefinition[] => {
+  if (isRecord(value) && 'roles' in value) {
+    return extractRoleDefinitions(value.roles)
+  }
+
+  return sanitizeRoleDefinitions(extractItems(value))
+}
+
+const extractManagementCounts = (value: unknown): CircleManagementCounts => {
+  return isRecord(value) ? sanitizeManagementCounts(value.counts) : { ...DEFAULT_MANAGEMENT_COUNTS }
+}
+
+const extractManagementPermissionCatalog = (value: unknown): CircleManagementPermissionCatalogEntry[] => {
+  return isRecord(value) ? sanitizePermissionCatalog(value.permission_catalog) : []
+}
+
+const extractAssignedRoles = (member: CircleMemberState): CircleRoleDefinition[] => {
+  return sanitizeRoleDefinitions(member.assigned_roles)
+}
+
+const buildEffectivePermissions = (assignedRoles: CircleRoleDefinition[]): string[] => {
+  return [...new Set(assignedRoles.flatMap((role) => role.permissions))]
+}
+
+const deriveDisplayRole = (
+  member: CircleMemberState,
+  assignedRoles: CircleRoleDefinition[] = extractAssignedRoles(member),
+): CircleRole => {
+  const membershipRole = member.membership_role ?? (member.role === 'owner' ? 'owner' : 'member')
+  if (membershipRole === 'owner') {
+    return 'owner'
+  }
+
+  if (assignedRoles.some((role) => role.slug === 'group-admin')) {
+    return 'admin'
+  }
+
+  if (assignedRoles.length > 0) {
+    return 'moderator'
+  }
+
+  return member.role === 'owner' ? 'owner' : member.role
+}
+
+const deriveRoleAssignmentsFromMembers = (members: CircleMemberState[]): CircleRoleAssignment[] => {
+  return members.map((member) => {
+    const roleAssignment: CircleRoleAssignment = {
+      id: member.id,
+      user_id: member.user_id,
+      role: deriveDisplayRole(member),
+      assigned_at: member.joined_at,
+    }
+
+    if (member.user) {
+      roleAssignment.user = member.user
+    }
+
+    return roleAssignment
+  })
+}
+
+const getRoleStoreService = (circlesService: CirclesServiceInstance): Partial<CircleRoleStoreService> => {
+  // The shared service layer is mid-migration; runtime method checks let the store
+  // support both the legacy member-role API and the new RBAC role-definition API.
+  return circlesService as unknown as Partial<CircleRoleStoreService>
+}
+
+interface CirclesState {
+  circles: Circle[]
+  currentCircle: Circle | null
+  members: Record<string, CircleMemberState[]>
+  joinRequests: Record<string, JoinRequest[]>
+  joinRequestsPagination: Record<string, CursorPaginationState>
+  managementActors: Record<string, CircleActorContext>
+  managementSections: Record<string, CircleManagementSection[]>
+  managementBootstrapLoading: Record<string, boolean>
+  managementBootstrapError: Record<string, string | null>
+  managementSectionLoading: Record<string, ManagementSectionLoadingState>
+  managementSectionErrors: Record<string, ManagementSectionErrorState>
+  managementBootstrappedAt: Record<string, string>
+  roleDefinitions: Record<string, CircleRoleDefinition[]>
+  roleDefinitionsPagination: Record<string, CursorPaginationState>
+  managementCounts: Record<string, CircleManagementCounts>
+  managementPermissionCatalog: Record<string, CircleManagementPermissionCatalogEntry[]>
+  // Compatibility cache for legacy consumers still reading per-member display roles.
+  roleAssignments: Record<string, CircleRoleAssignment[]>
+  roleAssignmentsPagination: Record<string, CursorPaginationState>
+  reports: Record<string, CircleModerationReport[]>
+  reportsPagination: Record<string, CursorPaginationState>
+  bans: Record<string, CircleBanRecord[]>
+  bansPagination: Record<string, CursorPaginationState>
+  mutes: Record<string, CircleMuteRecord[]>
+  mutesPagination: Record<string, CursorPaginationState>
+  auditLog: Record<string, CircleModerationAuditLogEntry[]>
+  auditLogPagination: Record<string, CursorPaginationState>
+  automodRules: Record<string, CircleAutomodRule[]>
+  automodRulesPagination: Record<string, CursorPaginationState>
+  pendingRequestCircleIds: string[]
+  loading: boolean
+  error: string | null
+  pagination: {
+    cursor: string | null
+    hasMore: boolean
+  }
+  activeFilterKey: string
+  circlesByFilter: Record<string, Circle[]>
+  paginationByFilter: Record<string, CursorPaginationState>
+  fetchedFilterKeys: Record<string, boolean>
+  membersPagination: Record<string, {
+    cursor: string | null
+    hasMore: boolean
+  }>
+  filters: CircleFilters
+}
+
+export type CirclesStoreReturn = ReturnType<ReturnType<typeof createCirclesStoreDefinition>>
+
+export function createCirclesStoreDefinition(config: CirclesStoreConfig) {
+  const {
+    storeId = 'circles',
+    circlesService,
+    getErrorMessage,
+    persist,
+  } = config
+
+  return defineStore(storeId, {
+    state: (): CirclesState => ({
+      circles: [],
+      currentCircle: null,
+      members: {},
+      joinRequests: {},
+      joinRequestsPagination: {},
+      managementActors: {},
+      managementSections: {},
+      managementBootstrapLoading: {},
+      managementBootstrapError: {},
+      managementSectionLoading: {},
+      managementSectionErrors: {},
+      managementBootstrappedAt: {},
+      roleDefinitions: {},
+      roleDefinitionsPagination: {},
+      managementCounts: {},
+      managementPermissionCatalog: {},
+      roleAssignments: {},
+      roleAssignmentsPagination: {},
+      reports: {},
+      reportsPagination: {},
+      bans: {},
+      bansPagination: {},
+      mutes: {},
+      mutesPagination: {},
+      auditLog: {},
+      auditLogPagination: {},
+      automodRules: {},
+      automodRulesPagination: {},
+      pendingRequestCircleIds: [],
+      loading: false,
+      error: null,
+      pagination: defaultPaginationState(),
+      activeFilterKey: DEFAULT_FILTER_KEY,
+      circlesByFilter: {
+        [DEFAULT_FILTER_KEY]: []
+      },
+      paginationByFilter: {
+        [DEFAULT_FILTER_KEY]: defaultPaginationState()
+      },
+      fetchedFilterKeys: {},
+      membersPagination: {},
+      filters: {}
+    }),
+
+    getters: {
+      userCircles: (state) => sanitizeCircleCollection(state.circles).filter(c =>
+        c.is_member || c.user_role === 'owner'
+      ),
+
+      joinableCircles: (state) => sanitizeCircleCollection(state.circles).filter(c =>
+        c.visibility === 'public' && !c.is_member && c.can_join
+      ),
+
+      managedCircles: (state) => sanitizeCircleCollection(state.circles).filter(c =>
+        c.user_role === 'owner' || c.can_manage
+      ),
+
+      filteredCircles: (state) => {
+        let filtered = [...sanitizeCircleCollection(state.circles)]
+
+        if (state.filters.membership === 'joined') {
+          filtered = filtered.filter(c => c.is_member || c.user_role === 'owner')
+        } else if (state.filters.membership === 'managed') {
+          filtered = filtered.filter(c => c.user_role === 'owner' || c.can_manage)
+        } else if (state.filters.membership === 'available') {
+          filtered = filtered.filter(c => !c.is_member && c.can_join)
+        }
+
+        if (state.filters.visibility) {
+          filtered = filtered.filter(c => c.visibility === state.filters.visibility)
+        }
+
+        if (state.filters.search) {
+          const searchTerm = state.filters.search.toLowerCase()
+          filtered = filtered.filter(c =>
+            c.name.toLowerCase().includes(searchTerm) ||
+            (c.description && c.description.toLowerCase().includes(searchTerm))
+          )
+        }
+
+        return filtered
+      },
+
+      getCircleById: (state) => (id: string) => {
+        return sanitizeCircleCollection(state.circles).find(c => c.id === id) || null
+      },
+
+      getCircleMembers: (state) => (circleId: string) => {
+        return state.members[circleId] || []
+      },
+
+      getMemberCount: (state) => (circleId: string) => {
+        const circle = sanitizeCircleCollection(state.circles).find(c => c.id === circleId)
+        return circle?.member_count || 0
+      },
+
+      getManagementActor: (state) => (circleId: string) => {
+        return state.managementActors[circleId] ?? null
+      },
+
+      getManagementSections: (state) => (circleId: string) => {
+        return state.managementSections[circleId] ?? []
+      },
+
+      getRoleDefinitions: (state) => (circleId: string) => {
+        return state.roleDefinitions[circleId] ?? []
+      },
+
+      getManagementCounts: (state) => (circleId: string) => {
+        return state.managementCounts[circleId] ?? { ...DEFAULT_MANAGEMENT_COUNTS }
+      },
+
+      getManagementPermissionCatalog: (state) => (circleId: string) => {
+        return state.managementPermissionCatalog[circleId] ?? []
+      },
+
+      getRoleAssignments: (state) => (circleId: string) => {
+        return state.roleAssignments[circleId] ?? []
+      },
+
+      getModerationReports: (state) => (circleId: string) => {
+        return state.reports[circleId] ?? []
+      },
+
+      getBanRecords: (state) => (circleId: string) => {
+        return state.bans[circleId] ?? []
+      },
+
+      getMuteRecords: (state) => (circleId: string) => {
+        return state.mutes[circleId] ?? []
+      },
+
+      getAuditLogEntries: (state) => (circleId: string) => {
+        return state.auditLog[circleId] ?? []
+      },
+
+      getAutomodRules: (state) => (circleId: string) => {
+        return state.automodRules[circleId] ?? []
+      }
+    },
+
+    actions: {
+      setFilters(filters: CircleFilters) {
+        const currentKey = this.activeFilterKey
+        this.circlesByFilter[currentKey] = [...this.circles]
+        this.paginationByFilter[currentKey] = { ...this.pagination }
+
+        const nextFilters = normalizeFilters(filters)
+        const nextKey = buildFilterKey(nextFilters)
+
+        this.filters = nextFilters
+        this.activeFilterKey = nextKey
+
+        const cachedCircles = this.circlesByFilter[nextKey]
+        const cachedPagination = this.paginationByFilter[nextKey]
+
+        if (cachedCircles) {
+          this.circles = sanitizeCircleCollection(cachedCircles)
+        } else {
+          this.circles = []
+          this.circlesByFilter[nextKey] = []
+        }
+
+        if (cachedPagination) {
+          this.pagination = { ...cachedPagination }
+        } else {
+          const defaultPagination = defaultPaginationState()
+          this.pagination = defaultPagination
+          this.paginationByFilter[nextKey] = { ...defaultPagination }
+        }
+      },
+
+      clearFilters() {
+        this.setFilters({})
+      },
+
+      hasFetchedCurrentFilter(): boolean {
+        return this.fetchedFilterKeys[this.activeFilterKey] === true
+      },
+
+      ensureManagementState(circleId: string) {
+        if (!this.managementSectionLoading[circleId]) {
+          this.managementSectionLoading[circleId] = {}
+        }
+
+        if (!this.managementSectionErrors[circleId]) {
+          this.managementSectionErrors[circleId] = {}
+        }
+
+        if (!this.roleDefinitionsPagination[circleId]) {
+          this.roleDefinitionsPagination[circleId] = emptyPaginationState()
+        }
+
+        if (!this.managementCounts[circleId]) {
+          this.managementCounts[circleId] = { ...DEFAULT_MANAGEMENT_COUNTS }
+        }
+
+        if (!this.managementPermissionCatalog[circleId]) {
+          this.managementPermissionCatalog[circleId] = []
+        }
+
+        if (!this.roleAssignmentsPagination[circleId]) {
+          this.roleAssignmentsPagination[circleId] = emptyPaginationState()
+        }
+
+        if (!this.reportsPagination[circleId]) {
+          this.reportsPagination[circleId] = emptyPaginationState()
+        }
+
+        if (!this.bansPagination[circleId]) {
+          this.bansPagination[circleId] = emptyPaginationState()
+        }
+
+        if (!this.mutesPagination[circleId]) {
+          this.mutesPagination[circleId] = emptyPaginationState()
+        }
+
+        if (!this.auditLogPagination[circleId]) {
+          this.auditLogPagination[circleId] = emptyPaginationState()
+        }
+
+        if (!this.automodRulesPagination[circleId]) {
+          this.automodRulesPagination[circleId] = emptyPaginationState()
+        }
+
+        if (!this.joinRequestsPagination[circleId]) {
+          this.joinRequestsPagination[circleId] = emptyPaginationState()
+        }
+      },
+
+      syncRoleAssignmentCompatibility(circleId: string) {
+        this.ensureManagementState(circleId)
+        this.roleAssignments[circleId] = deriveRoleAssignmentsFromMembers(this.members[circleId] ?? [])
+        this.roleAssignmentsPagination[circleId] = emptyPaginationState()
+      },
+
+      setRoleDefinitionsState(circleId: string, roles: CircleRoleDefinition[], pagination: CursorPaginationState) {
+        this.ensureManagementState(circleId)
+        this.roleDefinitions[circleId] = [...roles]
+        this.roleDefinitionsPagination[circleId] = { ...pagination }
+        this.managementCounts[circleId] = {
+          ...DEFAULT_MANAGEMENT_COUNTS,
+          ...(this.managementCounts[circleId] ?? {}),
+          roles: roles.length,
+        }
+      },
+
+      upsertRoleDefinitionState(circleId: string, role: CircleRoleDefinition) {
+        this.ensureManagementState(circleId)
+        const existingRoles = this.roleDefinitions[circleId] ?? []
+        const existingIndex = existingRoles.findIndex((candidate) => candidate.id === role.id)
+        const nextRoles = [...existingRoles]
+
+        if (existingIndex === -1) {
+          nextRoles.unshift(role)
+        } else {
+          nextRoles.splice(existingIndex, 1, role)
+        }
+
+        this.setRoleDefinitionsState(circleId, nextRoles, this.roleDefinitionsPagination[circleId] ?? emptyPaginationState())
+      },
+
+      removeRoleDefinitionState(circleId: string, roleId: string) {
+        this.ensureManagementState(circleId)
+        const nextRoles = (this.roleDefinitions[circleId] ?? []).filter((role) => role.id !== roleId)
+        this.setRoleDefinitionsState(circleId, nextRoles, this.roleDefinitionsPagination[circleId] ?? emptyPaginationState())
+      },
+
+      updateMemberRoleState(circleId: string, userId: string, patch: Partial<CircleMemberState>) {
+        const members = this.members[circleId]
+        if (!members) {
+          return
+        }
+
+        const memberIndex = members.findIndex((member) => member.user_id === userId || member.user?.id === userId)
+        if (memberIndex === -1) {
+          return
+        }
+
+        const member = members[memberIndex]
+        if (!member) {
+          return
+        }
+
+        members[memberIndex] = {
+          ...member,
+          ...patch,
+        }
+
+        this.syncRoleAssignmentCompatibility(circleId)
+      },
+
+      applyMemberRoleAssignments(
+        circleId: string,
+        userId: string,
+        assignedRoles: CircleRoleDefinition[],
+        effectivePermissions?: string[],
+      ) {
+        const members = this.members[circleId]
+        if (!members) {
+          return
+        }
+
+        const member = members.find((candidate) => candidate.user_id === userId || candidate.user?.id === userId)
+        if (!member) {
+          return
+        }
+
+        const membershipRole = member.membership_role ?? (member.role === 'owner' ? 'owner' : 'member')
+        const displayRole = membershipRole === 'owner'
+          ? 'owner'
+          : deriveDisplayRole(member, assignedRoles)
+
+        this.updateMemberRoleState(circleId, userId, {
+          membership_role: membershipRole,
+          display_role: displayRole,
+          role: displayRole,
+          assigned_roles: assignedRoles,
+          effective_permissions: effectivePermissions ?? buildEffectivePermissions(assignedRoles),
+        })
+      },
+
+      setManagementSectionLoading(circleId: string, key: ManagementCollectionKey, loading: boolean) {
+        this.ensureManagementState(circleId)
+        this.managementSectionLoading[circleId] = {
+          ...this.managementSectionLoading[circleId],
+          [key]: loading,
+        }
+      },
+
+      setManagementSectionError(circleId: string, key: ManagementCollectionKey, error: string | null) {
+        this.ensureManagementState(circleId)
+        this.managementSectionErrors[circleId] = {
+          ...this.managementSectionErrors[circleId],
+          [key]: error,
+        }
+      },
+
+      applyCircleSnapshot(circle: Circle) {
+        const existingIndex = this.circles.findIndex((candidate) => candidate.id === circle.id || candidate.slug === circle.slug)
+        if (existingIndex === -1) {
+          this.circles.unshift(circle)
+        } else {
+          this.circles.splice(existingIndex, 1, circle)
+        }
+
+        if (this.currentCircle?.id === circle.id || this.currentCircle?.slug === circle.slug) {
+          this.currentCircle = circle
+        }
+
+        this.circlesByFilter[this.activeFilterKey] = [...this.circles]
+
+        if (circle.actor) {
+          this.managementActors[circle.id] = circle.actor
+          this.managementSections[circle.id] = [...circle.actor.managementSections]
+        }
+      },
+
+      applyManagementBootstrap(bootstrap: CircleManagementBootstrap) {
+        const circleId = bootstrap.circle.id
+        this.ensureManagementState(circleId)
+        this.applyCircleSnapshot(bootstrap.circle)
+        this.currentCircle = bootstrap.circle
+        this.managementActors[circleId] = bootstrap.actor
+        this.managementSections[circleId] = [...bootstrap.management_sections]
+        this.managementCounts[circleId] = extractManagementCounts(bootstrap)
+        this.managementPermissionCatalog[circleId] = extractManagementPermissionCatalog(bootstrap)
+        this.managementBootstrapError[circleId] = null
+        this.managementBootstrappedAt[circleId] = new Date().toISOString()
+
+        this.members[circleId] = [...bootstrap.members.data]
+        this.membersPagination[circleId] = toCursorPaginationState(bootstrap.members)
+        this.joinRequests[circleId] = [...bootstrap.requests.data]
+        this.joinRequestsPagination[circleId] = toCursorPaginationState(bootstrap.requests)
+        this.setRoleDefinitionsState(
+          circleId,
+          extractRoleDefinitions(bootstrap),
+          toUnknownCursorPaginationState(isRecord(bootstrap) ? bootstrap.roles : null),
+        )
+        this.syncRoleAssignmentCompatibility(circleId)
+        this.reports[circleId] = [...bootstrap.reports.data]
+        this.reportsPagination[circleId] = toCursorPaginationState(bootstrap.reports)
+        this.bans[circleId] = [...bootstrap.bans.data]
+        this.bansPagination[circleId] = toCursorPaginationState(bootstrap.bans)
+        this.mutes[circleId] = [...bootstrap.mutes.data]
+        this.mutesPagination[circleId] = toCursorPaginationState(bootstrap.mutes)
+        this.auditLog[circleId] = [...bootstrap.audit.data]
+        this.auditLogPagination[circleId] = toCursorPaginationState(bootstrap.audit)
+        this.automodRules[circleId] = [...bootstrap.automod.data]
+        this.automodRulesPagination[circleId] = toCursorPaginationState(bootstrap.automod)
+
+        this.managementSectionErrors[circleId] = {}
+      },
+
+      async fetchCircles(refresh = false) {
+        const filterKey = this.activeFilterKey || buildFilterKey(this.filters)
+        this.activeFilterKey = filterKey
+
+        if (!this.circlesByFilter[filterKey]) {
+          this.circlesByFilter[filterKey] = []
+        }
+
+        if (!this.paginationByFilter[filterKey]) {
+          this.paginationByFilter[filterKey] = defaultPaginationState()
+        }
+
+        if (refresh) {
+          const defaultPagination = defaultPaginationState()
+          this.circlesByFilter[filterKey] = []
+          this.paginationByFilter[filterKey] = defaultPagination
+          this.circles = []
+          this.pagination = { ...defaultPagination }
+        }
+
+        const cursorState = this.paginationByFilter[filterKey]
+        if (!refresh && !cursorState.hasMore) {
+          return
+        }
+
+        this.loading = true
+        this.error = null
+
+        try {
+          const response = await circlesService.list(cursorState.cursor, this.filters)
+          const sanitizedResponseData = sanitizeCirclesPayload(response.data)
+          const nextCircles = refresh
+            ? [...sanitizedResponseData]
+            : mergeUniqueCircles(sanitizeCircleCollection(this.circlesByFilter[filterKey]), sanitizedResponseData)
+          const nextPagination: CursorPaginationState = {
+            cursor: response.meta?.pagination?.next_cursor || null,
+            hasMore: response.meta?.pagination?.has_more ?? Boolean(response.meta?.pagination?.next_cursor),
+          }
+
+          this.circlesByFilter[filterKey] = sanitizeCircleCollection(nextCircles)
+          this.paginationByFilter[filterKey] = nextPagination
+          this.fetchedFilterKeys[filterKey] = true
+
+          if (this.activeFilterKey !== filterKey) {
+            return
+          }
+
+          this.circles = sanitizeCircleCollection(nextCircles)
+          this.pagination = { ...nextPagination }
+        } catch (error: unknown) {
+          this.error = getErrorMessage(error)
+        } finally {
+          this.loading = false
+        }
+      },
+
+      async fetchCircle(id: string) {
+        this.loading = true
+        this.error = null
+
+        try {
+          const circle = await circlesService.get(id)
+          this.currentCircle = circle
+          this.applyCircleSnapshot(circle)
+          return circle
+        } catch (error: unknown) {
+          this.error = getErrorMessage(error)
+          throw error
+        } finally {
+          this.loading = false
+        }
+      },
+
+      async createCircle(data: CircleCreateInput) {
+        this.loading = true
+        this.error = null
+
+        try {
+          const result = await circlesService.create(data)
+          const newCircle = await circlesService.get(result.id)
+          this.applyCircleSnapshot(newCircle)
+          this.currentCircle = newCircle
+
+          return newCircle
+        } catch (error: unknown) {
+          this.error = getErrorMessage(error)
+          throw error
+        } finally {
+          this.loading = false
+        }
+      },
+
+      async updateCircle(id: string, data: CircleUpdateInput) {
+        this.loading = true
+        this.error = null
+
+        try {
+          const updatedCircle = await circlesService.update(id, data)
+          this.applyCircleSnapshot(updatedCircle)
+          this.currentCircle = updatedCircle
+
+          return updatedCircle
+        } catch (error: unknown) {
+          this.error = getErrorMessage(error)
+          throw error
+        } finally {
+          this.loading = false
+        }
+      },
+
+      async deleteCircle(id: string) {
+        this.loading = true
+        this.error = null
+
+        try {
+          await circlesService.delete(id)
+          this.circles = this.circles.filter(c => c.id !== id)
+
+          if (this.currentCircle?.id === id) {
+            this.currentCircle = null
+          }
+
+          delete this.members[id]
+          delete this.membersPagination[id]
+          delete this.joinRequests[id]
+          delete this.joinRequestsPagination[id]
+          delete this.managementActors[id]
+          delete this.managementSections[id]
+          delete this.managementBootstrapLoading[id]
+          delete this.managementBootstrapError[id]
+          delete this.managementSectionLoading[id]
+          delete this.managementSectionErrors[id]
+          delete this.managementBootstrappedAt[id]
+          delete this.roleDefinitions[id]
+          delete this.roleDefinitionsPagination[id]
+          delete this.managementCounts[id]
+          delete this.managementPermissionCatalog[id]
+          delete this.roleAssignments[id]
+          delete this.roleAssignmentsPagination[id]
+          delete this.reports[id]
+          delete this.reportsPagination[id]
+          delete this.bans[id]
+          delete this.bansPagination[id]
+          delete this.mutes[id]
+          delete this.mutesPagination[id]
+          delete this.auditLog[id]
+          delete this.auditLogPagination[id]
+          delete this.automodRules[id]
+          delete this.automodRulesPagination[id]
+        } catch (error: unknown) {
+          this.error = getErrorMessage(error)
+          throw error
+        } finally {
+          this.loading = false
+        }
+      },
+
+      async joinCircle(id: string) {
+        this.error = null
+
+        try {
+          await circlesService.join(id)
+
+          const circleIndex = this.circles.findIndex(c => c.id === id)
+          if (circleIndex !== -1) {
+            const circle = this.circles[circleIndex]
+            if (!circle) {
+              return
+            }
+
+            this.circles.splice(circleIndex, 1, {
+              ...circle,
+              is_member: true,
+              user_role: 'member',
+              member_count: (circle.member_count || 0) + 1,
+              can_join: false,
+              can_leave: true
+            })
+          }
+
+          if (this.currentCircle?.id === id) {
+            this.currentCircle = {
+              ...this.currentCircle,
+              is_member: true,
+              user_role: 'member',
+              member_count: (this.currentCircle.member_count || 0) + 1,
+              can_join: false,
+              can_leave: true
+            }
+          }
+        } catch (error: unknown) {
+          this.error = getErrorMessage(error)
+          throw error
+        }
+      },
+
+      async leaveCircle(id: string) {
+        this.error = null
+
+        try {
+          await circlesService.leave(id)
+
+          const circleIndex = this.circles.findIndex(c => c.id === id)
+          if (circleIndex !== -1) {
+            const circle = this.circles[circleIndex]
+            if (!circle) {
+              return
+            }
+
+            this.circles.splice(circleIndex, 1, {
+              ...circle,
+              is_member: false,
+              user_role: null,
+              member_count: Math.max((circle.member_count || 0) - 1, 0),
+              can_join: circle.visibility === 'public',
+              can_leave: false,
+              can_request_to_join: circle.visibility !== 'public',
+              has_pending_request: false
+            })
+          }
+
+          this.pendingRequestCircleIds = this.pendingRequestCircleIds.filter(cid => cid !== id)
+
+          if (this.currentCircle?.id === id) {
+            this.currentCircle = {
+              ...this.currentCircle,
+              is_member: false,
+              user_role: null,
+              member_count: Math.max((this.currentCircle.member_count || 0) - 1, 0),
+              can_join: this.currentCircle.visibility === 'public',
+              can_leave: false,
+              can_request_to_join: this.currentCircle.visibility !== 'public',
+              has_pending_request: false
+            }
+          }
+        } catch (error: unknown) {
+          this.error = getErrorMessage(error)
+          throw error
+        }
+      },
+
+      applyLiveMemberCount(circleId: string, memberCount: number) {
+        const nextCount = Math.max(memberCount, 0)
+
+        const circleIndex = this.circles.findIndex(c => c.id === circleId)
+        if (circleIndex !== -1) {
+          const circle = this.circles[circleIndex]
+          if (circle) {
+            this.circles.splice(circleIndex, 1, {
+              ...circle,
+              member_count: nextCount
+            })
+          }
+        }
+
+        if (this.currentCircle?.id === circleId) {
+          this.currentCircle = {
+            ...this.currentCircle,
+            member_count: nextCount
+          }
+        }
+      },
+
+      async fetchMembers(circleId: string, refresh = false) {
+        if (refresh) {
+          this.members[circleId] = []
+          this.membersPagination[circleId] = {
+            cursor: null,
+            hasMore: true
+          }
+        }
+
+        this.loading = true
+        this.error = null
+
+        try {
+          const pagination = this.membersPagination[circleId] || { cursor: null, hasMore: true }
+          const response = await circlesService.getMembers(circleId, pagination.cursor)
+
+          if (refresh) {
+            this.members[circleId] = response.data
+          } else {
+            this.members[circleId] = [
+              ...(this.members[circleId] || []),
+              ...response.data
+            ]
+          }
+
+          this.membersPagination[circleId] = toCursorPaginationState(response)
+          this.syncRoleAssignmentCompatibility(circleId)
+        } catch (error: unknown) {
+          this.error = getErrorMessage(error)
+          throw error
+        } finally {
+          this.loading = false
+        }
+      },
+
+      addMember(circleId: string, member: CircleMemberState) {
+        if (!this.members[circleId]) {
+          this.members[circleId] = []
+        }
+
+        if (!this.members[circleId].find(m => m.id === member.id)) {
+          this.members[circleId].push(member)
+          this.syncRoleAssignmentCompatibility(circleId)
+
+          const circleIndex = this.circles.findIndex(c => c.id === circleId)
+          if (circleIndex !== -1) {
+            const circle = this.circles[circleIndex]
+            if (circle) {
+              circle.member_count = (circle.member_count || 0) + 1
+            }
+          }
+
+          if (this.currentCircle?.id === circleId) {
+            this.currentCircle.member_count = (this.currentCircle.member_count || 0) + 1
+          }
+        }
+      },
+
+      removeMember(circleId: string, userId: string) {
+        if (this.members[circleId]) {
+          const nextMembers = this.members[circleId].filter(
+            m => m.user_id !== userId && m.user?.id !== userId
+          )
+          this.members[circleId] = nextMembers
+          this.syncRoleAssignmentCompatibility(circleId)
+          const nextCount = nextMembers.length
+
+          const circleIndex = this.circles.findIndex(c => c.id === circleId)
+          if (circleIndex !== -1) {
+            const circle = this.circles[circleIndex]
+            if (circle) {
+              circle.member_count = nextCount
+            }
+          }
+
+          if (this.currentCircle?.id === circleId) {
+            this.currentCircle.member_count = nextCount
+          }
+
+          return
+        }
+
+        const circleIndex = this.circles.findIndex(c => c.id === circleId)
+        if (circleIndex !== -1) {
+          const circle = this.circles[circleIndex]
+          if (circle) {
+            circle.member_count = Math.max((circle.member_count || 0) - 1, 0)
+          }
+        }
+
+        if (this.currentCircle?.id === circleId) {
+          this.currentCircle.member_count = Math.max((this.currentCircle.member_count || 0) - 1, 0)
+        }
+      },
+
+      async changeMemberRole(circleId: string, userId: string, newRole: 'admin' | 'member') {
+        this.error = null
+
+        try {
+          await circlesService.changeMemberRole(circleId, userId, newRole)
+
+          const assignedRoles = newRole === 'admin'
+            ? (this.roleDefinitions[circleId] ?? []).filter((role) => role.slug === 'group-admin')
+            : []
+
+          if (newRole === 'admin' && assignedRoles.length === 0) {
+            this.updateMemberRoleState(circleId, userId, {
+              membership_role: 'member',
+              display_role: 'admin',
+              role: 'admin',
+              assigned_roles: [],
+              effective_permissions: [],
+            })
+            return
+          }
+
+          if (newRole === 'member') {
+            this.updateMemberRoleState(circleId, userId, {
+              membership_role: 'member',
+              display_role: 'member',
+              role: 'member',
+              assigned_roles: [],
+              effective_permissions: [],
+            })
+            return
+          }
+
+          this.applyMemberRoleAssignments(
+            circleId,
+            userId,
+            assignedRoles,
+            buildEffectivePermissions(assignedRoles),
+          )
+        } catch (error: unknown) {
+          this.error = getErrorMessage(error)
+          throw error
+        }
+      },
+
+      async removeMemberFromCircle(circleId: string, userId: string) {
+        this.error = null
+
+        try {
+          await circlesService.removeMember(circleId, userId)
+          this.removeMember(circleId, userId)
+        } catch (error: unknown) {
+          this.error = getErrorMessage(error)
+          throw error
+        }
+      },
+
+      async muteMemberInCircle(circleId: string, userId: string, options?: CircleMuteMemberOptions) {
+        this.error = null
+
+        try {
+          await circlesService.muteMember(circleId, userId, options)
+          await Promise.allSettled([
+            this.fetchMutes(circleId, true),
+            this.fetchAuditLog(circleId, true),
+          ])
+        } catch (error: unknown) {
+          this.error = getErrorMessage(error)
+          throw error
+        }
+      },
+
+      async bootstrapManagement(circleId: string) {
+        this.ensureManagementState(circleId)
+        this.managementBootstrapLoading[circleId] = true
+        this.managementBootstrapError[circleId] = null
+
+        try {
+          const bootstrap = await circlesService.getManagementBootstrap(circleId)
+          this.applyManagementBootstrap(bootstrap)
+          return bootstrap
+        } catch (error: unknown) {
+          const message = getErrorMessage(error)
+          this.managementBootstrapError[circleId] = message
+          this.error = message
+          throw error
+        } finally {
+          this.managementBootstrapLoading[circleId] = false
+        }
+      },
+
+      async fetchRoleDefinitions(circleId: string, refresh = false) {
+        this.setManagementSectionLoading(circleId, 'roles', true)
+        this.setManagementSectionError(circleId, 'roles', null)
+
+        try {
+          const roleService = getRoleStoreService(circlesService)
+          const cursor = refresh ? null : this.roleDefinitionsPagination[circleId]?.cursor ?? null
+
+          let response: unknown
+          let usedLegacyListRolesFallback = false
+
+          if (typeof roleService.fetchRoleDefinitions === 'function') {
+            response = await roleService.fetchRoleDefinitions(circleId, cursor)
+          } else if (typeof roleService.listRoleDefinitions === 'function') {
+            response = await roleService.listRoleDefinitions(circleId, cursor)
+          } else if (typeof roleService.listRoles === 'function') {
+            usedLegacyListRolesFallback = true
+            response = await roleService.listRoles(circleId, cursor)
+          } else {
+            response = []
+          }
+
+          const incomingRoles = extractRoleDefinitions(response)
+          if (usedLegacyListRolesFallback && incomingRoles.length === 0) {
+            return this.roleDefinitions[circleId] ?? []
+          }
+
+          const nextRoles = refresh
+            ? [...incomingRoles]
+            : [
+                ...(this.roleDefinitions[circleId] ?? []),
+                ...incomingRoles.filter((role) => !(this.roleDefinitions[circleId] ?? []).some((existing) => existing.id === role.id)),
+              ]
+
+          this.setRoleDefinitionsState(circleId, nextRoles, toUnknownCursorPaginationState(response))
+          return nextRoles
+        } catch (error: unknown) {
+          const message = getErrorMessage(error)
+          this.setManagementSectionError(circleId, 'roles', message)
+          throw error
+        } finally {
+          this.setManagementSectionLoading(circleId, 'roles', false)
+        }
+      },
+
+      async createRoleDefinition(circleId: string, input: CircleRoleDefinitionInput) {
+        this.error = null
+
+        try {
+          const roleService = getRoleStoreService(circlesService)
+          let response: unknown
+
+          if (typeof roleService.createRoleDefinition === 'function') {
+            response = await roleService.createRoleDefinition(circleId, input)
+          } else if (typeof roleService.createRole === 'function') {
+            response = await roleService.createRole(circleId, input)
+          } else {
+            throw new Error('Role definition creation is unavailable.')
+          }
+
+          const role = normalizeRoleDefinition(response)
+          if (role === null) {
+            throw new Error('Invalid role definition payload')
+          }
+
+          this.upsertRoleDefinitionState(circleId, role)
+          await this.fetchRoleDefinitions(circleId, true)
+          return role
+        } catch (error: unknown) {
+          this.error = getErrorMessage(error)
+          throw error
+        }
+      },
+
+      async updateRoleDefinition(circleId: string, roleId: string, input: CircleRoleDefinitionUpdateInput) {
+        this.error = null
+
+        try {
+          const roleService = getRoleStoreService(circlesService)
+          let response: unknown
+
+          if (typeof roleService.updateRoleDefinition === 'function') {
+            response = await roleService.updateRoleDefinition(circleId, roleId, input)
+          } else if (typeof roleService.updateRole === 'function') {
+            response = await roleService.updateRole(circleId, roleId, input)
+          } else {
+            throw new Error('Role definition updates are unavailable.')
+          }
+
+          const role = normalizeRoleDefinition(response)
+          if (role === null) {
+            throw new Error('Invalid role definition payload')
+          }
+
+          this.upsertRoleDefinitionState(circleId, role)
+          await this.fetchRoleDefinitions(circleId, true)
+          return role
+        } catch (error: unknown) {
+          this.error = getErrorMessage(error)
+          throw error
+        }
+      },
+
+      async replaceRoleDefinitionPermissions(circleId: string, roleId: string, permissions: string[]) {
+        this.error = null
+
+        try {
+          const roleService = getRoleStoreService(circlesService)
+          const sanitizedPermissions = sanitizePermissionKeys(permissions)
+          let response: unknown
+
+          if (typeof roleService.replaceRoleDefinitionPermissions === 'function') {
+            response = await roleService.replaceRoleDefinitionPermissions(circleId, roleId, sanitizedPermissions)
+          } else if (typeof roleService.replaceRolePermissions === 'function') {
+            response = await roleService.replaceRolePermissions(circleId, roleId, sanitizedPermissions)
+          } else {
+            throw new Error('Role permission updates are unavailable.')
+          }
+
+          const role = normalizeRoleDefinition(response)
+          if (role === null) {
+            throw new Error('Invalid role definition payload')
+          }
+
+          this.upsertRoleDefinitionState(circleId, role)
+          await this.fetchRoleDefinitions(circleId, true)
+          return role
+        } catch (error: unknown) {
+          this.error = getErrorMessage(error)
+          throw error
+        }
+      },
+
+      async archiveRoleDefinition(circleId: string, roleId: string) {
+        this.error = null
+
+        try {
+          const roleService = getRoleStoreService(circlesService)
+
+          if (typeof roleService.archiveRoleDefinition === 'function') {
+            await roleService.archiveRoleDefinition(circleId, roleId)
+          } else if (typeof roleService.archiveRole === 'function') {
+            await roleService.archiveRole(circleId, roleId)
+          } else {
+            throw new Error('Role archiving is unavailable.')
+          }
+
+          this.removeRoleDefinitionState(circleId, roleId)
+        } catch (error: unknown) {
+          this.error = getErrorMessage(error)
+          throw error
+        }
+      },
+
+      async assignMemberRoles(circleId: string, userId: string, roleIds: string[]) {
+        this.error = null
+
+        try {
+          const roleService = getRoleStoreService(circlesService)
+          const normalizedRoleIds = [...new Set(roleIds.filter((roleId) => roleId.trim().length > 0))]
+
+          if (typeof roleService.assignMemberRoles === 'function') {
+            const response = await roleService.assignMemberRoles(circleId, userId, normalizedRoleIds)
+            const responseRecord = isRecord(response) ? response : {}
+            const assignedRoles = sanitizeRoleDefinitions(responseRecord.assigned_roles)
+            const effectivePermissions = sanitizePermissionKeys(responseRecord.effective_permissions)
+
+            this.applyMemberRoleAssignments(circleId, userId, assignedRoles, effectivePermissions)
+            return {
+              assigned_roles: assignedRoles,
+              effective_permissions: effectivePermissions,
+            } satisfies CircleMemberRoleAssignmentResult
+          }
+
+          const selectedRoles = (this.roleDefinitions[circleId] ?? []).filter((role) => normalizedRoleIds.includes(role.id))
+          if (selectedRoles.length === 1 && selectedRoles[0]?.slug === 'group-admin') {
+            await this.changeMemberRole(circleId, userId, 'admin')
+            return {
+              assigned_roles: selectedRoles,
+              effective_permissions: buildEffectivePermissions(selectedRoles),
+            } satisfies CircleMemberRoleAssignmentResult
+          }
+
+          throw new Error('Member role assignment is unavailable.')
+        } catch (error: unknown) {
+          this.error = getErrorMessage(error)
+          throw error
+        }
+      },
+
+      async removeMemberRole(circleId: string, userId: string, roleId: string) {
+        this.error = null
+
+        try {
+          const roleService = getRoleStoreService(circlesService)
+          if (typeof roleService.removeMemberRole === 'function') {
+            await roleService.removeMemberRole(circleId, userId, roleId)
+          } else {
+            const member = (this.members[circleId] ?? []).find((candidate) => candidate.user_id === userId || candidate.user?.id === userId)
+            const assignedRoles = member ? extractAssignedRoles(member) : []
+            const nextAssignedRoles = assignedRoles.filter((role) => role.id !== roleId)
+            const removedRole = assignedRoles.find((role) => role.id === roleId)
+
+            if (removedRole?.slug === 'group-admin' && nextAssignedRoles.length === 0) {
+              await this.changeMemberRole(circleId, userId, 'member')
+              return
+            }
+
+            throw new Error('Member role removal is unavailable.')
+          }
+
+          const member = (this.members[circleId] ?? []).find((candidate) => candidate.user_id === userId || candidate.user?.id === userId)
+          const nextAssignedRoles = member
+            ? extractAssignedRoles(member).filter((role) => role.id !== roleId)
+            : []
+
+          if (nextAssignedRoles.length === 0) {
+            this.updateMemberRoleState(circleId, userId, {
+              membership_role: 'member',
+              display_role: 'member',
+              role: 'member',
+              assigned_roles: [],
+              effective_permissions: [],
+            })
+            return
+          }
+
+          this.applyMemberRoleAssignments(circleId, userId, nextAssignedRoles, buildEffectivePermissions(nextAssignedRoles))
+        } catch (error: unknown) {
+          this.error = getErrorMessage(error)
+          throw error
+        }
+      },
+
+      async fetchRoleAssignments(circleId: string, refresh = false) {
+        this.setManagementSectionLoading(circleId, 'roles', true)
+        this.setManagementSectionError(circleId, 'roles', null)
+
+        try {
+          if (refresh || !this.members[circleId]) {
+            await this.fetchMembers(circleId, refresh)
+          }
+
+          this.syncRoleAssignmentCompatibility(circleId)
+          return this.roleAssignments[circleId] ?? []
+        } catch (error: unknown) {
+          const message = getErrorMessage(error)
+          this.setManagementSectionError(circleId, 'roles', message)
+          throw error
+        } finally {
+          this.setManagementSectionLoading(circleId, 'roles', false)
+        }
+      },
+
+      async transferOwnership(circleId: string, userId: string) {
+        this.error = null
+
+        try {
+          await circlesService.transferOwnership(circleId, userId)
+          await this.bootstrapManagement(circleId)
+        } catch (error: unknown) {
+          this.error = getErrorMessage(error)
+          throw error
+        }
+      },
+
+      async fetchModerationReports(circleId: string, refresh = false, status: 'pending' | 'actioned' | 'dismissed' = 'pending') {
+        this.setManagementSectionLoading(circleId, 'reports', true)
+        this.setManagementSectionError(circleId, 'reports', null)
+
+        try {
+          const cursor = refresh ? null : this.reportsPagination[circleId]?.cursor ?? null
+          const response = await circlesService.listModerationReports(circleId, cursor, status)
+          const nextReports = refresh
+            ? [...response.data]
+            : [
+                ...(this.reports[circleId] ?? []),
+                ...response.data.filter((report) => !(this.reports[circleId] ?? []).some((existing) => existing.id === report.id)),
+              ]
+
+          this.reports[circleId] = nextReports
+          this.reportsPagination[circleId] = toCursorPaginationState(response)
+          return nextReports
+        } catch (error: unknown) {
+          const message = getErrorMessage(error)
+          this.setManagementSectionError(circleId, 'reports', message)
+          throw error
+        } finally {
+          this.setManagementSectionLoading(circleId, 'reports', false)
+        }
+      },
+
+      async reportMemberInCircle(circleId: string, subjectUserId: string, category: string, notes?: string) {
+        this.error = null
+
+        try {
+          await circlesService.reportMember(circleId, subjectUserId, category, notes)
+          await Promise.allSettled([
+            this.fetchModerationReports(circleId, true),
+            this.fetchAuditLog(circleId, true),
+          ])
+        } catch (error: unknown) {
+          this.error = getErrorMessage(error)
+          throw error
+        }
+      },
+
+      async resolveReportInCircle(circleId: string, reportId: string, decision: CircleReportDecision, resolutionNotes?: string) {
+        this.error = null
+
+        try {
+          const result = await circlesService.resolveModerationReport(circleId, reportId, decision, resolutionNotes)
+          if (this.reports[circleId]) {
+            this.reports[circleId] = this.reports[circleId].map((report) => (
+              report.id === reportId
+                ? {
+                    ...report,
+                    status: result.status === 'actioned' || result.status === 'dismissed'
+                      ? result.status
+                      : report.status,
+                    resolution_notes: resolutionNotes ?? report.resolution_notes ?? null,
+                  }
+                : report
+            ))
+          }
+
+          await this.fetchAuditLog(circleId, true)
+          return result
+        } catch (error: unknown) {
+          this.error = getErrorMessage(error)
+          throw error
+        }
+      },
+
+      async fetchBans(circleId: string, refresh = false) {
+        this.setManagementSectionLoading(circleId, 'bans', true)
+        this.setManagementSectionError(circleId, 'bans', null)
+
+        try {
+          const cursor = refresh ? null : this.bansPagination[circleId]?.cursor ?? null
+          const response = await circlesService.listBans(circleId, cursor)
+          const nextBans = refresh
+            ? [...response.data]
+            : [
+                ...(this.bans[circleId] ?? []),
+                ...response.data.filter((ban) => !(this.bans[circleId] ?? []).some((existing) => existing.id === ban.id)),
+              ]
+
+          this.bans[circleId] = nextBans
+          this.bansPagination[circleId] = toCursorPaginationState(response)
+          return nextBans
+        } catch (error: unknown) {
+          const message = getErrorMessage(error)
+          this.setManagementSectionError(circleId, 'bans', message)
+          throw error
+        } finally {
+          this.setManagementSectionLoading(circleId, 'bans', false)
+        }
+      },
+
+      async banMemberInCircle(circleId: string, userId: string, options?: { reason?: string }) {
+        this.error = null
+
+        try {
+          await circlesService.banMember(circleId, userId, options)
+          this.removeMember(circleId, userId)
+          await Promise.allSettled([
+            this.fetchBans(circleId, true),
+            this.fetchAuditLog(circleId, true),
+            this.fetchRoleAssignments(circleId, true),
+          ])
+        } catch (error: unknown) {
+          this.error = getErrorMessage(error)
+          throw error
+        }
+      },
+
+      async unbanMemberInCircle(circleId: string, userId: string) {
+        this.error = null
+
+        try {
+          await circlesService.unbanMember(circleId, userId)
+          await Promise.allSettled([
+            this.fetchBans(circleId, true),
+            this.fetchAuditLog(circleId, true),
+          ])
+        } catch (error: unknown) {
+          this.error = getErrorMessage(error)
+          throw error
+        }
+      },
+
+      async fetchMutes(circleId: string, refresh = false) {
+        this.setManagementSectionLoading(circleId, 'mutes', true)
+        this.setManagementSectionError(circleId, 'mutes', null)
+
+        try {
+          const cursor = refresh ? null : this.mutesPagination[circleId]?.cursor ?? null
+          const response = await circlesService.listMutes(circleId, cursor)
+          const nextMutes = refresh
+            ? [...response.data]
+            : [
+                ...(this.mutes[circleId] ?? []),
+                ...response.data.filter((mute) => !(this.mutes[circleId] ?? []).some((existing) => existing.id === mute.id)),
+              ]
+
+          this.mutes[circleId] = nextMutes
+          this.mutesPagination[circleId] = toCursorPaginationState(response)
+          return nextMutes
+        } catch (error: unknown) {
+          const message = getErrorMessage(error)
+          this.setManagementSectionError(circleId, 'mutes', message)
+          throw error
+        } finally {
+          this.setManagementSectionLoading(circleId, 'mutes', false)
+        }
+      },
+
+      async unmuteMemberInCircle(circleId: string, userId: string) {
+        this.error = null
+
+        try {
+          await circlesService.unmuteMember(circleId, userId)
+          await Promise.allSettled([
+            this.fetchMutes(circleId, true),
+            this.fetchAuditLog(circleId, true),
+          ])
+        } catch (error: unknown) {
+          this.error = getErrorMessage(error)
+          throw error
+        }
+      },
+
+      async fetchAuditLog(circleId: string, refresh = false) {
+        this.setManagementSectionLoading(circleId, 'audit', true)
+        this.setManagementSectionError(circleId, 'audit', null)
+
+        try {
+          const cursor = refresh ? null : this.auditLogPagination[circleId]?.cursor ?? null
+          const response = await circlesService.getModerationAuditLog(circleId, cursor)
+          const nextEntries = refresh
+            ? [...response.data]
+            : [
+                ...(this.auditLog[circleId] ?? []),
+                ...response.data.filter((entry) => !(this.auditLog[circleId] ?? []).some((existing) => existing.id === entry.id)),
+              ]
+
+          this.auditLog[circleId] = nextEntries
+          this.auditLogPagination[circleId] = toCursorPaginationState(response)
+          return nextEntries
+        } catch (error: unknown) {
+          const message = getErrorMessage(error)
+          this.setManagementSectionError(circleId, 'audit', message)
+          throw error
+        } finally {
+          this.setManagementSectionLoading(circleId, 'audit', false)
+        }
+      },
+
+      async fetchAutomodRules(circleId: string, refresh = false) {
+        this.setManagementSectionLoading(circleId, 'automod', true)
+        this.setManagementSectionError(circleId, 'automod', null)
+
+        try {
+          const cursor = refresh ? null : this.automodRulesPagination[circleId]?.cursor ?? null
+          const response = await circlesService.listAutomodRules(circleId, cursor)
+          const nextRules = refresh
+            ? [...response.data]
+            : [
+                ...(this.automodRules[circleId] ?? []),
+                ...response.data.filter((rule) => !(this.automodRules[circleId] ?? []).some((existing) => existing.id === rule.id)),
+              ]
+
+          this.automodRules[circleId] = nextRules
+          this.automodRulesPagination[circleId] = toCursorPaginationState(response)
+          return nextRules
+        } catch (error: unknown) {
+          const message = getErrorMessage(error)
+          this.setManagementSectionError(circleId, 'automod', message)
+          throw error
+        } finally {
+          this.setManagementSectionLoading(circleId, 'automod', false)
+        }
+      },
+
+      async createAutomodRuleInCircle(circleId: string, input: CircleAutomodRuleInput) {
+        this.error = null
+
+        try {
+          const rule = await circlesService.createAutomodRule(circleId, input)
+          this.automodRules[circleId] = [rule, ...(this.automodRules[circleId] ?? [])]
+          await this.fetchAuditLog(circleId, true)
+          return rule
+        } catch (error: unknown) {
+          this.error = getErrorMessage(error)
+          throw error
+        }
+      },
+
+      async updateAutomodRuleInCircle(circleId: string, ruleId: string, input: Partial<CircleAutomodRuleInput>) {
+        this.error = null
+
+        try {
+          const updatedRule = await circlesService.updateAutomodRule(circleId, ruleId, input)
+          this.automodRules[circleId] = (this.automodRules[circleId] ?? []).map((rule) => (
+            rule.id === updatedRule.id ? updatedRule : rule
+          ))
+          await this.fetchAuditLog(circleId, true)
+          return updatedRule
+        } catch (error: unknown) {
+          this.error = getErrorMessage(error)
+          throw error
+        }
+      },
+
+      async deleteAutomodRuleInCircle(circleId: string, ruleId: string) {
+        this.error = null
+
+        try {
+          await circlesService.deleteAutomodRule(circleId, ruleId)
+          this.automodRules[circleId] = (this.automodRules[circleId] ?? []).filter((rule) => rule.id !== ruleId)
+          await this.fetchAuditLog(circleId, true)
+        } catch (error: unknown) {
+          this.error = getErrorMessage(error)
+          throw error
+        }
+      },
+
+      async requestJoinCircle(id: string, message?: string) {
+        this.error = null
+
+        try {
+          await circlesService.requestToJoin(id, message)
+
+          if (!this.pendingRequestCircleIds.includes(id)) {
+            this.pendingRequestCircleIds.push(id)
+          }
+
+          const circleIndex = this.circles.findIndex(c => c.id === id)
+          if (circleIndex !== -1) {
+            const circle = this.circles[circleIndex]
+            if (!circle) {
+              return
+            }
+
+            this.circles.splice(circleIndex, 1, {
+              ...circle,
+              has_pending_request: true,
+              can_request_to_join: false
+            })
+          }
+
+          if (this.currentCircle?.id === id) {
+            this.currentCircle = {
+              ...this.currentCircle,
+              has_pending_request: true,
+              can_request_to_join: false
+            }
+          }
+        } catch (error: unknown) {
+          this.error = getErrorMessage(error)
+          throw error
+        }
+      },
+
+      async fetchJoinRequests(circleId: string, status?: string) {
+        this.error = null
+        this.setManagementSectionLoading(circleId, 'requests', true)
+        this.setManagementSectionError(circleId, 'requests', null)
+
+        try {
+          const response = await circlesService.listJoinRequests(circleId, null, status)
+          this.joinRequests[circleId] = response.data
+          this.joinRequestsPagination[circleId] = toCursorPaginationState(response)
+        } catch (error: unknown) {
+          const message = getErrorMessage(error)
+          this.error = message
+          this.setManagementSectionError(circleId, 'requests', message)
+          throw error
+        } finally {
+          this.setManagementSectionLoading(circleId, 'requests', false)
+        }
+      },
+
+      async moderateJoinRequest(circleId: string, requestId: string, decision: 'approve' | 'reject') {
+        this.error = null
+
+        try {
+          await circlesService.moderateJoinRequest(circleId, requestId, decision)
+
+          if (this.joinRequests[circleId]) {
+            this.joinRequests[circleId] = this.joinRequests[circleId].filter(r => r.id !== requestId)
+          }
+
+          if (decision === 'approve') {
+            const circleIndex = this.circles.findIndex(c => c.id === circleId)
+            if (circleIndex !== -1) {
+              const circle = this.circles[circleIndex]
+              if (!circle) {
+                return
+              }
+
+              this.circles.splice(circleIndex, 1, {
+                ...circle,
+                member_count: (circle.member_count || 0) + 1
+              })
+            }
+
+            if (this.currentCircle?.id === circleId) {
+              this.currentCircle = {
+                ...this.currentCircle,
+                member_count: (this.currentCircle.member_count || 0) + 1
+              }
+            }
+          }
+        } catch (error: unknown) {
+          this.error = getErrorMessage(error)
+          throw error
+        }
+      },
+
+      async syncPendingJoinRequestStatuses() {
+        const circleIds = new Set<string>(this.pendingRequestCircleIds)
+
+        for (const circle of this.circles) {
+          if (circle.has_pending_request) {
+            circleIds.add(circle.id)
+          }
+        }
+
+        if (circleIds.size === 0) {
+          return
+        }
+
+        for (const circleId of circleIds) {
+          try {
+            const latestCircle = await circlesService.get(circleId)
+
+            const circleIndex = this.circles.findIndex(circle => circle.id === circleId)
+            if (circleIndex !== -1) {
+              const existingCircle = this.circles[circleIndex]
+              if (!existingCircle) {
+                continue
+              }
+
+              this.circles.splice(circleIndex, 1, {
+                ...existingCircle,
+                ...latestCircle
+              })
+            }
+
+            if (this.currentCircle?.id === circleId) {
+              this.currentCircle = {
+                ...this.currentCircle,
+                ...latestCircle
+              }
+            }
+
+            if (latestCircle.has_pending_request) {
+              if (!this.pendingRequestCircleIds.includes(circleId)) {
+                this.pendingRequestCircleIds.push(circleId)
+              }
+
+              continue
+            }
+
+            this.pendingRequestCircleIds = this.pendingRequestCircleIds.filter(id => id !== circleId)
+          } catch {
+            // Best-effort reconciliation: ignore per-circle failures and retry next poll cycle.
+          }
+        }
+      },
+
+      async createInviteLink(circleId: string, options?: Pick<CircleInviteLinkOptions, 'max_uses' | 'expires_in_minutes'>): Promise<InviteLink> {
+        this.error = null
+
+        try {
+          return await circlesService.createInviteLink(circleId, options)
+        } catch (error: unknown) {
+          this.error = getErrorMessage(error)
+          throw error
+        }
+      },
+
+      hasPendingRequest(circleId: string): boolean {
+        return this.pendingRequestCircleIds.includes(circleId)
+      },
+
+      clearState() {
+        this.circles = []
+        this.currentCircle = null
+        this.members = {}
+        this.joinRequests = {}
+        this.joinRequestsPagination = {}
+        this.managementActors = {}
+        this.managementSections = {}
+        this.managementBootstrapLoading = {}
+        this.managementBootstrapError = {}
+        this.managementSectionLoading = {}
+        this.managementSectionErrors = {}
+        this.managementBootstrappedAt = {}
+        this.roleDefinitions = {}
+        this.roleDefinitionsPagination = {}
+        this.managementCounts = {}
+        this.managementPermissionCatalog = {}
+        this.roleAssignments = {}
+        this.roleAssignmentsPagination = {}
+        this.reports = {}
+        this.reportsPagination = {}
+        this.bans = {}
+        this.bansPagination = {}
+        this.mutes = {}
+        this.mutesPagination = {}
+        this.auditLog = {}
+        this.auditLogPagination = {}
+        this.automodRules = {}
+        this.automodRulesPagination = {}
+        this.pendingRequestCircleIds = []
+        this.loading = false
+        this.error = null
+        this.pagination = {
+          cursor: null,
+          hasMore: true
+        }
+        this.activeFilterKey = DEFAULT_FILTER_KEY
+        this.circlesByFilter = {
+          [DEFAULT_FILTER_KEY]: []
+        }
+        this.paginationByFilter = {
+          [DEFAULT_FILTER_KEY]: defaultPaginationState()
+        }
+        this.fetchedFilterKeys = {}
+        this.membersPagination = {}
+        this.filters = {}
+      }
+    },
+
+    ...(persist ? { persist } : {})
+  })
+}