papers/hanzo-webhooks/sections/02-event-sourcing-model.tex

\section{Event Sourcing Model}


\subsection{Event Definition}

\begin{definition}[Commerce Event]
An event $e$ is a tuple $(id, type, timestamp, merchant, payload, version)$ where:
\begin{itemize}
    \item $id$: globally unique event identifier
    \item $type \in \mathcal{T}$: event type (e.g., \texttt{order.created})
    \item $timestamp$: event occurrence time
    \item $merchant$: merchant identifier
    \item $payload$: JSON event data
    \item $version$: schema version for evolution
\end{itemize}
\end{definition}

\subsection{Event Types}

Events are organized hierarchically:

\begin{lstlisting}[caption=Event Type Hierarchy]
order.*
  order.created
  order.updated
  order.fulfilled
  order.cancelled
  order.refunded

payment.*
  payment.authorized
  payment.captured
  payment.failed
  payment.refunded

customer.*
  customer.created
  customer.updated
  customer.deleted

product.*
  product.created
  product.updated
  product.deleted

inventory.*
  inventory.updated
  inventory.low_stock
\end{lstlisting}

\subsection{Event Store}

Events are durably stored before delivery:

\begin{definition}[Event Store]
The event store $\mathcal{S}$ provides:
\begin{itemize}
    \item $append(e)$: Durably store event $e$
    \item $read(id)$: Retrieve event by ID
    \item $stream(merchant, after)$: Stream events after cursor
\end{itemize}
\end{definition}

\begin{theorem}[Event Durability]
Once $append(e)$ returns successfully, event $e$ is durably stored:
\[
append(e) = success \Rightarrow e \in \mathcal{S} \text{ permanently}
\]
\end{theorem}

Implementation uses PostgreSQL with write-ahead logging, replicated across three availability zones.