How to Build TypeScript Citations in RAG Apps That Don't Break on Refactor

A common pattern in retrieval-augmented generation (RAG) apps uses array index numbers as citation references, but these break whenever chunk sizes change, rerankers are added, or conversations are persisted. The proposed fix replaces positional indices with stable source references containing a document ID, content hash, character offsets, and document revision. TypeScript's type system is used to enforce that every claim must carry at least one source reference, making uncited claims a compile-time error. Short opaque labels are passed to the language model during inference and resolved back to stable references server-side, preventing hallucinated or stale citations from reaching storage. A resolution layer then classifies each stored reference as exact, moved, stale, or gone, ensuring the render path accurately reflects the current state of the source document.