"""Role model with permissions and optional hierarchy."""

from pydantic import BaseModel


class Role(BaseModel):
    """A role with a name, permissions, and optional parent roles.

    Permissions are strings in 'resource_type:action' format (e.g., 'documents:read',
    '*:*'). They are parsed into Permission objects internally by the engine.

    Parent roles enable hierarchy (Phase 2+). In Phase 1, only flat role membership
    is used — parents are accepted in the schema but not resolved during evaluation.

    Example:
        admin = Role(name="admin", permissions=["*:*"])
        editor = Role(name="editor", permissions=["documents:write", "documents:read"])
    """

    name: str
    permissions: list[str] = []
    parents: list[str] = []
