# #region AuditService [C:3] [TYPE Module] [SEMANTICS clean-release, audit, report, trail, release]
# @BRIEF Provide lightweight audit hooks for clean release preparation/check/report lifecycle.
# @LAYER Infrastructure
# @RELATION DEPENDS_ON -> [LoggerModule]
# @INVARIANT  Audit hooks are append-only log actions.
# @PRE  Logger configured
# @POST  Audit events appended to log
# @SIDE_EFFECT  Writes audit events to logger and repository
# @DATA_CONTRACT  AuditAction -> LogEntry

from __future__ import annotations

from datetime import UTC, datetime
from typing import Any
from uuid import uuid4

from ...core.logger import logger


def _append_event(repository, payload: dict[str, Any]) -> None:
    if repository is not None and hasattr(repository, "append_audit_event"):
        repository.append_audit_event(payload)


def audit_preparation(
    candidate_id: str, status: str, repository=None, actor: str = "system"
) -> None:
    logger.reason(
        f"clean-release preparation candidate={candidate_id} status={status}"
    )
    _append_event(
        repository,
        {
            "id": f"audit-{uuid4()}",
            "action": "PREPARATION",
            "candidate_id": candidate_id,
            "actor": actor,
            "status": status,
            "timestamp": datetime.now(UTC).isoformat(),
        },
    )


def audit_check_run(
    check_run_id: str,
    final_status: str,
    repository=None,
    *,
    candidate_id: str | None = None,
    actor: str = "system",
) -> None:
    logger.reflect(
        f"clean-release check_run={check_run_id} final_status={final_status}"
    )
    _append_event(
        repository,
        {
            "id": f"audit-{uuid4()}",
            "action": "CHECK_RUN",
            "run_id": check_run_id,
            "candidate_id": candidate_id,
            "actor": actor,
            "status": final_status,
            "timestamp": datetime.now(UTC).isoformat(),
        },
    )


def audit_violation(
    run_id: str,
    stage_name: str,
    code: str,
    repository=None,
    *,
    candidate_id: str | None = None,
    actor: str = "system",
) -> None:
    logger.explore(
        f"clean-release violation run_id={run_id} stage={stage_name} code={code}"
    )
    _append_event(
        repository,
        {
            "id": f"audit-{uuid4()}",
            "action": "VIOLATION",
            "run_id": run_id,
            "candidate_id": candidate_id,
            "actor": actor,
            "stage_name": stage_name,
            "code": code,
            "timestamp": datetime.now(UTC).isoformat(),
        },
    )


def audit_report(
    report_id: str,
    candidate_id: str,
    repository=None,
    *,
    run_id: str | None = None,
    actor: str = "system",
) -> None:
    logger.explore(
        f"clean-release report_id={report_id} candidate={candidate_id}"
    )
    _append_event(
        repository,
        {
            "id": f"audit-{uuid4()}",
            "action": "REPORT",
            "report_id": report_id,
            "run_id": run_id,
            "candidate_id": candidate_id,
            "actor": actor,
            "timestamp": datetime.now(UTC).isoformat(),
        },
    )


# #endregion AuditService
