Settings.json hot-reload flow

Overview

The whitelist exposes settings.json loading primitives and a globalConfig mtime cache with a freshness watcher, but no settings.json-specific mtime cache or watcher function is visible fn:loadSettingsFromDisk. What follows traces the settings read path and the adjacent globalConfig freshness mechanism that the whitelist does expose state:globalConfigCache.

Steps

1. A caller entering the settings read path goes through getInitialSettings, which delegates to getSettingsWithErrors fn:getInitialSettings.
2. getSettingsWithErrors first checks the session-level cache and returns early on hit, avoiding any disk I/O fn:getSettingsWithErrors.
3. On miss, it calls loadSettingsFromDisk and stores the result back into the session cache via setSessionSettingsCache fn:getSettingsWithErrors.
4. loadSettingsFromDisk guards against reentry using isLoadingSettings, then merges plugin settings and iterates enabled setting sources in priority order fn:loadSettingsFromDisk.
5. Per-source parsing is memoized through parseFileCache and perSourceCache, so repeat reads within one load avoid re-parsing files state:parseFileCache.
6. Invalidation of the merged cache happens through resetSettingsCache, which clears the session cache plus both per-source maps in one shot fn:resetSettingsCache.
7. One caller of that reset is getRemoteManagedSettingsSyncFromCache, which flushes the merged cache the first time the remote-managed policy layer becomes visible so the next read re-merges with that layer included fn:getRemoteManagedSettingsSyncFromCache.
8. For the adjacent globalConfig file, getGlobalConfig takes a pure memory fast path off globalConfigCache.config and only falls through to a sync stat+read on the cold startup miss fn:getGlobalConfig.
9. On that slow path it stats the file before reading, recording mtimeMs into the cache so a concurrent writer racing the read self-corrects on the next watcher tick fn:getGlobalConfig.
10. A background freshness watcher — gated by freshnessWatcherStarted — is what picks up other instances' writes without blocking the fast path, per the comment in getGlobalConfig state:freshnessWatcherStarted.
11. Writes back to settings go through updateSettingsForSource, which bypasses perSourceCache explicitly because mergeWith mutates its target and a failed write would otherwise leak unpersisted state into the cache fn:updateSettingsForSource.
12. The whitelist does not expose a settings.json mtime cache, file watcher, or change-detection function — only the session/per-source/parse caches above and the separate globalConfig mtime+watcher pair — so a full settings-file hot-reload path cannot be traced from the provided source fn:loadSettingsFromDisk.

State touched

• state:sessionSettingsCache
• state:perSourceCache
• state:parseFileCache
• state:isLoadingSettings
• state:pluginSettingsBase
• state:globalConfigCache
• state:freshnessWatcherStarted
• state:configCacheHits
• state:configCacheMisses
• state:sessionCache

Decisions

(None in whitelist — the decisions section is empty fn:getSettingsWithErrors.)