# #region audit_repository [C:3] [TYPE Module] [SEMANTICS clean-release, audit, repository, persistence, crud]
# @BRIEF Persist and query audit logs for clean release operations.
# @LAYER Infrastructure
# @RELATION DEPENDS_ON -> [EXT:Library:sqlalchemy]


from sqlalchemy.orm import Session

from src.core.logger import belief_scope
from src.models.clean_release import CleanReleaseAuditLog


class AuditRepository:
    """
    @PURPOSE: Encapsulates database operations for CleanReleaseAuditLog.
    """
    def __init__(self, db: Session):
        self.db = db

    def log(self, action: str, actor: str, candidate_id: str | None = None, details: dict | None = None) -> CleanReleaseAuditLog:
        """
        @PURPOSE: Create an audit log entry.
        """
        with belief_scope("AuditRepository.log"):
            entry = CleanReleaseAuditLog(
                action=action,
                actor=actor,
                candidate_id=candidate_id,
                details_json=details or {}
            )
            self.db.add(entry)
            self.db.commit()
            self.db.refresh(entry)
            return entry

    def list_by_candidate(self, candidate_id: str) -> list[CleanReleaseAuditLog]:
        """
        @PURPOSE: List all audit entries for a specific candidate.
        """
        with belief_scope("AuditRepository.list_by_candidate"):
            return self.db.query(CleanReleaseAuditLog).filter(CleanReleaseAuditLog.candidate_id == candidate_id).all()

# #endregion audit_repository
