From 2290a1dc5a575c0875524571c64ee24968851855 Mon Sep 17 00:00:00 2001 From: Tam Nhu Tran Date: Thu, 30 Apr 2026 15:44:34 -0400 Subject: [PATCH] docs(config-facade): clarify cache coherence contract Document that uncached reads (loadOrCreateUnifiedConfig) bypass the cache and callers should use invalidateConfigCache() if they mix uncached reads with cached writes outside the facade. Resolves remaining PR-Agent concern from #1150 comment. --- src/config/config-loader-facade.ts | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/src/config/config-loader-facade.ts b/src/config/config-loader-facade.ts index e6b17ad2..19188ba4 100644 --- a/src/config/config-loader-facade.ts +++ b/src/config/config-loader-facade.ts @@ -5,10 +5,14 @@ * Re-exports read-only functions from unified-config-loader and config-manager, * and provides cache-coherent write wrappers that keep the memoization cache in sync. * - * IMPORTANT: Raw write functions (saveUnifiedConfig, mutateUnifiedConfig, - * updateUnifiedConfig) are NOT re-exported here. Use the cache-coherent - * wrappers (saveConfig, mutateConfig, updateConfig) instead. If you need - * the raw functions, import directly from './unified-config-loader'. + * IMPORTANT: + * - Raw write functions (saveUnifiedConfig, mutateUnifiedConfig, + * updateUnifiedConfig) are NOT re-exported here. Use the cache-coherent + * wrappers (saveConfig, mutateConfig, updateConfig) instead. + * - `loadOrCreateUnifiedConfig` and `loadUnifiedConfig` are re-exported as + * uncached reads. If you need cached reads, use `getCachedConfig()`. + * If you use an uncached read followed by a write outside this facade, + * call `invalidateConfigCache()` to keep the cache coherent. * * Usage: * import { getCachedConfig, saveConfig, mutateConfig } from '../config/config-loader-facade';