"""Structured audit-event helpers for workflow execution.

Events complement runtime state: state answers where a workflow is now, while the
event history explains how it got there. The recorder only appends new immutable
WorkflowEvent values to the tuple stored on WorkflowRun.
"""

from __future__ import annotations

from typing import Any
from uuid import uuid4

from src.schemas import EventType, WorkflowEvent, WorkflowRun, utc_now


def record_event(
    run: WorkflowRun,
    event_type: EventType,
    *,
    node_id: str | None = None,
    details: dict[str, Any] | None = None,
) -> WorkflowEvent:
    """Append one structured audit event to a workflow run and return it."""

    event = WorkflowEvent(
        event_id=str(uuid4()),
        run_id=run.run_id,
        event_type=event_type,
        node_id=node_id,
        details=dict(details or {}),
        timestamp=utc_now(),
    )
    run.events = (*run.events, event)
    return event