papers/lp-225-xss-x-chain-settlement-spine/sections/07-coexistence.tex

\section{Coexistence: parallel and unified, side by side}
\label{sec:coexistence}

\textbf{This section is the governing constraint on the entire LP.} XSS
is \emph{not} a hard cutover. The current parallel-ledger model stays
working in full, and the unified X-lock-settled model is built
\emph{alongside} it, \emph{selectable}, so that both can be run, tested,
compared, and validated against each other before any value migrates.
Nothing in the migration (Section~\ref{sec:migration}) removes a working
path until the unified path has been proven equal to it on the same
inputs.

\subsection{What stays working}

Untouched and live throughout:

\begin{itemize}[leftmargin=2em,nosep]
\item The D-Chain \texttt{available}/\texttt{locked} ledger and
  \texttt{settleFills} (\texttt{lx/dex/pkg/dchain/}).
\item The P-Chain \texttt{utxoDB}, \texttt{StakeOuts}, and reward
  minting (\texttt{vms/platformvm/}).
\item The atomic \texttt{ImportTx}/\texttt{ExportTx} rail on X, P, and
  the DEX proxy, and the LP-224~\cite{lp224} carried-custody
  consensus wire.
\end{itemize}

\subsection{What is added alongside}

\begin{itemize}[leftmargin=2em,nosep]
\item The five X primitives (Section~\ref{sec:primitives}) as new X
  transaction types --- additive, behind activation
  (Section~\ref{sec:migration}, P1).
\item For each module, a \emph{second} funding/settlement path: order
  funding via \texttt{lockID} \emph{in addition to} the
  \texttt{available} ledger (D); stake via X stake-lock \emph{in
  addition to} \texttt{StakeOuts} (P).
\end{itemize}

\subsection{The selector}

A single configuration flag per module --- call it
\texttt{settlement\_mode} $\in \{\texttt{parallel},\texttt{unified},
\texttt{shadow}\}$:

\begin{itemize}[leftmargin=2em,nosep]
\item \texttt{parallel}: today's behavior, authoritative. The unified
  path is not exercised.
\item \texttt{shadow}: both paths run on every operation; the
  \texttt{parallel} path is authoritative (its outputs ship), the
  \texttt{unified} path runs in lockstep and its outputs are recorded
  and compared, never shipped. This is the validation mode.
\item \texttt{unified}: the X-lock path is authoritative; the parallel
  ledger is no longer consulted.
\end{itemize}

\noindent A module advances \texttt{parallel} $\to$ \texttt{shadow}
$\to$ \texttt{unified} only after the comparison harness reports zero
divergence over a defined corpus and load. The flag is per-module so D
can be \texttt{unified} while P is still \texttt{shadow}.

\subsection{The comparison harness}

In \texttt{shadow} mode the harness drives both paths from one input
stream and asserts equality on four axes. Any mismatch is a hard stop.

\begin{enumerate}[leftmargin=2em]
\item \textbf{Identical settlement outputs.} For every operation
  (deposit/order/match/withdraw, stake/unstake/reward), the set of
  resulting outputs --- (owner, asset, amount) tuples for visible
  outputs; (commitment) for shielded --- produced by the parallel path
  must equal the set produced by the unified path, byte-for-byte on the
  canonical encoding. A buy that fills 0.7 of its size must leave the
  same balances/UTXOs under both. This is the primary correctness gate.
\item \textbf{Conservation holds in both.} Independently in each path:
  the parallel path's local invariant
  ($\texttt{sum(balance:)}+\texttt{sum(locked:)}$ constant for D;
  stake$+$rewards accounting for P) \emph{and} the unified path's global
  invariant (per asset: spendable $+$ locked $+$ shielded $=$ total,
  and visible $+$ shielded $=$ total). Both must hold at every step;
  the harness recomputes both after every operation.
\item \textbf{Replay / restart parity.} Persist, kill, and restart each
  path; re-derive state from the chain. Both paths must reach the same
  state they had before restart, and re-applying the same block bytes
  must be a pure function (the LP-224 determinism property generalized
  to locks). The harness checkpoints, restarts, and re-diffs.
\item \textbf{Performance delta.} Wall-clock and per-operation cost of
  the unified path relative to the parallel path, reported as a
  distribution, not a single number. \textbf{No performance figure is
  asserted in this document}; the harness \emph{measures} the delta so
  the decision to flip to \texttt{unified} is data-driven. (We do not
  reuse any throughput number here; the P3Q and starkfri verifiers have
  benchmark harnesses but no measured throughput is committed in the
  repo, so none is cited.)
\end{enumerate}

\subsection{Exit criterion}

A module flips \texttt{shadow} $\to$ \texttt{unified} only when, over an
agreed corpus (replayed mainnet-shaped traffic plus adversarial edge
cases: zero-fills, partial fills, expiries, timeouts, slashes) and an
agreed load, the harness reports: axis 1 zero divergence, axis 2 both
invariants hold throughout, axis 3 full replay/restart parity, and axis
4 a performance delta the operator accepts. Until then the parallel path
remains authoritative. There is no flag that skips the harness.