role

type ListFilter struct {
	TenantID        string  `json:"tenant_id,omitempty"`
	NamespacePath   *string `json:"namespace_path,omitempty"`
	NamespacePrefix string  `json:"namespace_prefix,omitempty"`
	IsSystem        *bool   `json:"is_system,omitempty"`
	IsDefault       *bool   `json:"is_default,omitempty"`
	ParentSlug      *string `json:"parent_slug,omitempty"`
	Search          string  `json:"search,omitempty"`
	Limit           int     `json:"limit,omitempty"`
	Offset          int     `json:"offset,omitempty"`
}

type Role struct {
	ID            id.RoleID      `json:"id" db:"id"`
	TenantID      string         `json:"tenant_id" db:"tenant_id"`
	NamespacePath string         `json:"namespace_path,omitempty" db:"namespace_path"`
	AppID         string         `json:"app_id" db:"app_id"`
	Name          string         `json:"name" db:"name"`
	Description   string         `json:"description,omitempty" db:"description"`
	Slug          string         `json:"slug" db:"slug"`
	IsSystem      bool           `json:"is_system" db:"is_system"`
	IsDefault     bool           `json:"is_default" db:"is_default"`
	ParentSlug    string         `json:"parent_slug,omitempty" db:"parent_slug"`
	MaxMembers    int            `json:"max_members,omitempty" db:"max_members"`
	Metadata      map[string]any `json:"metadata,omitempty" db:"metadata"`
	CreatedAt     time.Time      `json:"created_at" db:"created_at"`
	UpdatedAt     time.Time      `json:"updated_at" db:"updated_at"`
}

type Store interface {
	// CreateRole persists a new role.
	CreateRole(ctx context.Context, r *Role) error

	// GetRole retrieves a role by ID.
	GetRole(ctx context.Context, roleID id.RoleID) (*Role, error)

	// GetRoleBySlug retrieves a role by tenant, namespace, and slug.
	// Slugs are unique per (tenant_id, namespace_path); the namespace
	// argument disambiguates roles that share the same slug across
	// different namespace scopes.
	GetRoleBySlug(ctx context.Context, tenantID, namespacePath, slug string) (*Role, error)

	// UpdateRole persists changes to a role.
	UpdateRole(ctx context.Context, r *Role) error

	// DeleteRole removes a role by ID.
	DeleteRole(ctx context.Context, roleID id.RoleID) error

	// ListRoles returns roles matching the filter.
	ListRoles(ctx context.Context, filter *ListFilter) ([]*Role, error)

	// CountRoles returns the number of roles matching the filter.
	CountRoles(ctx context.Context, filter *ListFilter) (int64, error)

	// ListRolePermissions returns the full Permission records granted to a
	// role, resolved via JOIN against warden_permissions. Returning the full
	// records avoids the engine's previous N+1 GetPermission loop in the
	// RBAC evaluator.
	ListRolePermissions(ctx context.Context, roleID id.RoleID) ([]*permission.Permission, error)

	// AttachPermission links a permission to a role by natural key.
	// The (NamespacePath, Name) pair uniquely identifies a permission within
	// the role's tenant.
	AttachPermission(ctx context.Context, roleID id.RoleID, ref permission.Ref) error

	// DetachPermission removes a permission grant from a role.
	DetachPermission(ctx context.Context, roleID id.RoleID, ref permission.Ref) error

	// SetRolePermissions replaces all permission grants for a role.
	SetRolePermissions(ctx context.Context, roleID id.RoleID, refs []permission.Ref) error

	// ListChildRoles returns direct child roles of a parent within a tenant.
	// Children are inherently per-tenant since slugs are unique per tenant.
	ListChildRoles(ctx context.Context, tenantID, parentSlug string) ([]*Role, error)

	// DeleteRolesByTenant removes all roles for a tenant.
	DeleteRolesByTenant(ctx context.Context, tenantID string) error
}