% Troubleshooting and maintainer architecture.
\section{Recovery from Errors}\label{ch:trouble}

\subsection{Interpreting compiler diagnostics}

When you encounter an unexpected rendering or a compiler refusal, do not
despair!  \TeX{} tools are designed to assist you, and in \pkg{}, the golden rule
of debugging is simple: \textbf{read meaning before ink.}

Begin by opening the job's companion \tnfile{.tnlog} file and locating the
picture's coded diagnostic or boundary event.  Ask yourself: What mathematical
object should this tensor network represent?  A state $|\psi\rangle$ has open
physical indices; a matrix window has two open virtual indices; and a doubled
transfer window has four.  A fully contracted expectation value or partition
function has an empty boundary signature.  When inspecting an equation, compare the boundary signatures of each
side term by term, ensuring that all physical and virtual indices balance
across the equality.

{\small
\noindent
\begin{tabularx}{\linewidth}{@{}
  >{\raggedright\arraybackslash}p{35mm}
  >{\raggedright\arraybackslash}X@{}}
\toprule
Symptom & First correction \\
\midrule
An operator rendered as a scalar & State \tnkey{boundary=open}, or type the open
ports; an unstated side draws no leg. \\
A periodic trace looks like a cup & Use \tnkey{boundary=periodic} for same-row closure;
use side \tnval{cup} only between adjacent layers. \\
A label touches ink & Restore a documented metric or label band; do not hide
the problem with an undocumented coordinate offset. \\
Requested ink disappears & Treat it as an implementation defect.  Unsupported
ink must be a hard coded error, never a warning followed by omission. \\
\bottomrule
\end{tabularx}
}

A few simple habits will save you from the most common syntactic pitfalls:
Always enclose in curly braces any key value containing a comma or an equals sign
(for instance, \tnkey{east=}\tnval{\{cup=\$X\$\}}).  Remember that complex
conjugation is mathematical label notation and wire direction, not an internal
atom flag.  When creating a hole in a lattice, distinguish between
\tnkey{void=open} (where incident indices survive around the missing site) and
\tnkey{void=sealed} (which removes the site and its incident bonds entirely).

\subsection{The internal pipeline}

Behind the scenes, \pkg{} translates your declarations into vector ink through
seven strictly sequenced stages:

\begin{center}
\texttt{language -> model -> style/atoms -> geometry -> kernel layout ->
rendering -> events}.
\end{center}

Each stage owns a distinct responsibility: Language parses public declarations
and emits coded diagnostics.  Model normalizes those declarations into canonical
records.  Style manages metrics, atom descriptors, label bands, and
silhouettes.  Geometry computes frames, daylight separation, wire routing, and
crossings.  Layout handles genre-specific grid placement.  Rendering draws ink
faithfully without parsing syntax or altering topology.  Finally, Events
serializes the resolved model for auditing.

The top-level file \tnfile{tikz-tensor-networks.sty} is a logic-free load map.  Every internal
source file opens with a five-line contract declaring its consumed inputs,
promised outputs, owned private state, invariants, and downstream consumer.
Private control sequences follow a strict owner-prefixed convention, guarded by
an automated symbol census.

Full build and debugging workflows live in \tnfile{HACKING.md}, while the
underlying ownership contracts are detailed in \tnfile{ARCHITECTURE.md}.  Always
keep the maintainer's motto in mind: after every meaningful change, compile,
lint, audit the versioned event stream, and inspect the rendered pages.  Exit
codes verify compilation, but only your eyes can inspect the beauty of a diagram!