papers/lp-300-schema-registry/sections/07-cross-referencing-pattern.tex

\section{Cross-referencing pattern}
\label{sec:xref}

Every consuming LP's ``Wire schemas'' / ``Schema IDs'' / ``Precompile
slot'' section is now informative-only. LP-300 is normative. The
canonical pattern a consuming LP MUST use, with the wording lightly
adapted to taste:

\begin{lstlisting}
This LP allocates the following schema IDs (registered in
LP-300 sec.Master Table):

  - 0xD0 ConsensusVote
  - 0xD1 ConsensusProposal
  - 0xD2 ConsensusCert (mirrors 0x01 QuasarCert)
  - ...

This LP's "Wire schemas" section is informative only;
LP-300 is normative. For the master allocation map see
LP-300 sec.Master Table (TypeKind / ShapeKind /
Precompile slot).
\end{lstlisting}

The pattern has three load-bearing properties:

\begin{enumerate}[leftmargin=2em,nosep]
\item \textbf{List the rows the LP owns, but cite LP-300 for the
  table.} The consuming LP's reader needs to know which bytes are in
  play; the consuming LP does not need to duplicate the master
  registry to deliver that knowledge.
\item \textbf{Mark the local section informative.} If the consuming
  LP and LP-300 ever disagree -- a typo, an out-of-date Draft, a
  late-arriving amendment that hasn't propagated -- the disagreement
  is resolved in favor of LP-300. The ``informative only'' label is
  the operator-facing surface of that rule.
\item \textbf{Cite the binding map by section.} A reader who reaches
  the consuming LP via search lands on the local list, then follows
  the LP-300 cite to the binding map. The local list never grows
  stale beyond the LP-300 PR cycle.
\end{enumerate}

\subsection{What consuming LPs MUST NOT do}

\begin{itemize}[leftmargin=2em,nosep]
\item Re-state the master table. A consuming LP that mirrors the
  rows owned by other LPs is a maintenance liability; every LP-300
  amendment would have to chase every consuming-LP mirror.
\item Allocate a slot not in LP-300. A consuming LP that names a
  byte LP-300 doesn't have is making a unilateral claim. The
  amendment-first rule (\S\ref{sec:policy}) forbids this.
\item Silently change an allocation. Edits to the local row must
  follow an LP-300 amendment, not lead it.
\end{itemize}

\subsection{What consuming LPs SHOULD do}

\begin{itemize}[leftmargin=2em,nosep]
\item Inline a short rationale next to the local row. ``LP-300 row:
  \texttt{0xE8} \texttt{RollupBatchTx} -- chosen because the contiguous
  \texttt{0xE8..0xEF} tail leaves room for sequencer-rotation and
  cross-rollup-commit additions in \texttt{0xED..0xEF}.''
\item Cite the conflict resolution row (\S\ref{sec:conflicts}) when
  the LP's allocation was the result of a conflict resolution. Future
  readers need the audit trail.
\item Reference the namespace explicitly. ``LP-300 namespace 1
  (TypeKind)'' is unambiguous; ``LP-300 row \texttt{0x9010}'' is
  ambiguous because the same hex prefix could appear in multiple
  namespaces if not qualified.
\end{itemize}

\subsection{Audit checklist for the consuming LP}

Before promoting a consuming LP past Draft:

\begin{enumerate}[leftmargin=2em,nosep]
\item Every slot the LP names appears in LP-300 with the same Owner
  LP. (Cross-check against \S\ref{sec:typekind},
  \S\ref{sec:shapekind}, \S\ref{sec:precompile}.)
\item Every wrapper relationship (LP attaches to a slot owned by a
  different LP) is recorded in LP-300 with both LPs cited in the
  Owner LP column.
\item The consuming LP's local table is labeled informative and
  cites LP-300 as the binding map.
\item Any allocation change since the previous LP revision has a
  matching LP-300 amendment PR that was merged before the consuming
  LP's promotion PR.
\end{enumerate}

A consuming LP that fails any of these checks is not ready to
promote past Draft.