@dataclass
class TrailEvent:
    event_id: str         # UUID v4
    event_type: str       # namespaced event type
    timestamp: str        # ISO-8601 UTC
    actor_id: str         # who performed the action
    tenant_id: str        # tenant/org isolation key
    trace_id: str | None  # cross-system correlation
    session_id: str | None  # session grouping
    payload: dict         # domain-specific data
    prev_hash: str        # hash of previous event
    hash: str             # SHA-256 hash of this event
    signature: str | None # HMAC-SHA256 signature

interface TrailEvent {
  eventId: string;         // UUID v4
  eventType: string;       // namespaced event type
  timestamp: string;       // ISO-8601 UTC
  actorId: string;         // who performed the action
  tenantId: string;        // tenant/org isolation key
  traceId?: string;        // cross-system correlation
  sessionId?: string;      // session grouping
  payload: Record<string, unknown>;  // domain-specific data
  prevHash: string;        // hash of previous event
  hash: string;            // SHA-256 hash of this event
  signature?: string;      // HMAC-SHA256 signature
}

@dataclass
class QueryResult:
    events: list[TrailEvent]    # matching events
    next_cursor: str | None     # cursor for next page, None if no more

interface QueryResult {
  events: TrailEvent[];         // matching events
  nextCursor?: string;          // cursor for next page
}

@dataclass
class VerifyResult:
    intact: bool          # True if no tampering detected
    total: int            # number of events checked
    broken: list[int]     # indices of events that failed verification

interface VerifyResult {
  intact: boolean;        // true if no tampering detected
  total: number;          // number of events checked
  broken: number[];       // indices of events that failed verification
}