"""OwnedMixin — adds owner_id to any model for row-level ownership.

Usage:
    class Contact(Base, TenantMixin, OwnedMixin):
        ...

owner_id semantics:
- NULL → "tenant-owned" (visible to all with module permission)
- UUID → owned by that user (visible to owner + shared via entity_permissions)
- When creating: owner_id = current_user.id (set automatically by service layer)
- Transfer: only owner, admin, or system_admin can change owner_id
"""

from __future__ import annotations

import uuid

from sqlalchemy import ForeignKey, Index
from sqlalchemy.dialects.postgresql import UUID as PGUUID
from sqlalchemy.orm import Mapped, mapped_column


class OwnedMixin:
    """Mixin that adds owner_id column to a model."""

    owner_id: Mapped[uuid.UUID | None] = mapped_column(
        PGUUID(as_uuid=True),
        ForeignKey("users.id", ondelete="SET NULL"),
        nullable=True,
        index=True,
    )