Our catalog concurrency model is defined by several interacting pieces: the lock manager, MVCC and copy-on-write for the CollecitonCatalog, and sharding-specific state (CSS/DSS, critical sections...).

The documentation for the current model is spread across READMEs, design docs, tickets, and code comments, which makes it hard for server engineers and LLMs to know which locks and APIs to use and what guarantees they get.

This ticket proposes creating a single, authoritative document that explains the catalog concurrency control model and the primitives that compose it, linking to existing documents where applicable, and provides specific guidance for new and existing code.

This document should help answer questions like:

• Which DB/collection locks and modes are required before accessing the CSS/DSS?
• What's the correct lock ordering between MultiDocumentTransactionsBarrier, RSTL, Global, DB, Collection, DSS, CSS, and which patterns to avoid.
  • What are the exceptions to watch out for

Existing documentation

• Catalog Internals
• Concurrency Control