Guidelines:

Should include

• Which types of nodes does this exist on, and what is it used for on each?
• When is the cache consulted? E.g., for routing requests on namespaces
• When is the cache marked as stale?
• How is it decided whether to do an incremental refresh or full refresh?
• What are the operational caveats, e.g. are stale entries ever evicted or is there a memory limit on the cache size?

Code references

• The CatalogCache class
• Where the CatalogCache is informed of a StaleShardVersion