microsoft
diff --git a/‎sdk/cs/src/Catalog.cs‎
Lines changed: 135 additions & 32 deletions b/‎sdk/cs/src/Catalog.cs‎
Lines changed: 135 additions & 32 deletions
diff --git a/‎sdk/cs/src/Detail/Model.cs‎
Lines changed: 33 additions & 2 deletions b/‎sdk/cs/src/Detail/Model.cs‎
Lines changed: 33 additions & 2 deletions
diff --git a/‎sdk/cs/src/Detail/ModelVariant.cs‎
Lines changed: 19 additions & 2 deletions b/‎sdk/cs/src/Detail/ModelVariant.cs‎
Lines changed: 19 additions & 2 deletions
@@ -7,6 +7,7 @@
 namespace Microsoft.AI.Foundry.Local;
 using System;
 using System.Collections.Generic;
+using System.Linq;
 using System.Text.Json;
 using System.Threading.Tasks;
 
@@ -102,52 +103,113 @@ private async Task<List<IModel>> ListModelsImplAsync(CancellationToken? ct = nul
 
     private async Task<List<IModel>> GetCachedModelsImplAsync(CancellationToken? ct = null)
     {
+        await UpdateModels(ct).ConfigureAwait(false);
+
         var cachedModelIds = await Utils.GetCachedModelIdsAsync(_coreInterop, ct).ConfigureAwait(false);
+        return await ResolveModelIdsAsync(cachedModelIds, ct).ConfigureAwait(false);
+    }
+
+    private async Task<List<IModel>> GetLoadedModelsImplAsync(CancellationToken? ct = null)
+    {
+        await UpdateModels(ct).ConfigureAwait(false);
 
-        List<IModel> cachedModels = [];
-        foreach (var modelId in cachedModelIds)
+        var loadedModelIds = await _modelLoadManager.ListLoadedModelsAsync(ct).ConfigureAwait(false);
+        return await ResolveModelIdsAsync(loadedModelIds, ct).ConfigureAwait(false);
+    }
+
+    // Resolve a list of model ids against the in-memory catalog, self-healing once
+    // if any id is unknown (e.g. a manually-added BYOM model the SDK has not yet seen).
+    // Preserves the input order of modelIds (minus unknowns).
+    private async Task<List<IModel>> ResolveModelIdsAsync(string[] modelIds, CancellationToken? ct)
+    {
+        bool needsRefresh = false;
+        using (var disposable = await _lock.LockAsync().ConfigureAwait(false))
         {
-            if (_modelIdToModelVariant.TryGetValue(modelId, out ModelVariant? modelVariant))
+            foreach (var modelId in modelIds)
             {
-                cachedModels.Add(modelVariant);
+                if (!_modelIdToModelVariant.ContainsKey(modelId))
+                {
+                    needsRefresh = true;
+                    break;
+                }
             }
         }
 
-        return cachedModels;
-    }
-
-    private async Task<List<IModel>> GetLoadedModelsImplAsync(CancellationToken? ct = null)
-    {
-        var loadedModelIds = await _modelLoadManager.ListLoadedModelsAsync(ct).ConfigureAwait(false);
-        List<IModel> loadedModels = [];
+        if (needsRefresh)
+        {
+            await UpdateModels(ct, force: true).ConfigureAwait(false);
+        }
 
-        foreach (var modelId in loadedModelIds)
+        List<IModel> resolved = new(modelIds.Length);
+        using (var disposable = await _lock.LockAsync().ConfigureAwait(false))
         {
-            if (_modelIdToModelVariant.TryGetValue(modelId, out ModelVariant? modelVariant))
+            foreach (var modelId in modelIds)
             {
-                loadedModels.Add(modelVariant);
+                if (_modelIdToModelVariant.TryGetValue(modelId, out ModelVariant? variant))
+                {
+                    resolved.Add(variant);
+                }
             }
         }
 
-        return loadedModels;
+        return resolved;
     }
 
     private async Task<Model?> GetModelImplAsync(string modelAlias, CancellationToken? ct = null)
     {
+        if (string.IsNullOrWhiteSpace(modelAlias))
+        {
+            return null;
+        }
+
         await UpdateModels(ct).ConfigureAwait(false);
 
-        using var disposable = await _lock.LockAsync().ConfigureAwait(false);
-        _modelAliasToModel.TryGetValue(modelAlias, out Model? model);
+        Model? model;
+        using (var disposable = await _lock.LockAsync().ConfigureAwait(false))
+        {
+            _modelAliasToModel.TryGetValue(modelAlias, out model);
+        }
+        if (model is not null)
+        {
+            return model;
+        }
 
+        // Self-heal: the alias may belong to a BYOM model added to the cache
+        // directory after our last catalog refresh.
+        await UpdateModels(ct, force: true).ConfigureAwait(false);
+        using (var disposable = await _lock.LockAsync().ConfigureAwait(false))
+        {
+            _modelAliasToModel.TryGetValue(modelAlias, out model);
+        }
         return model;
     }
 
     private async Task<ModelVariant?> GetModelVariantImplAsync(string modelId, CancellationToken? ct = null)
     {
+        if (string.IsNullOrWhiteSpace(modelId))
+        {
+            return null;
+        }
+
         await UpdateModels(ct).ConfigureAwait(false);
 
-        using var disposable = await _lock.LockAsync().ConfigureAwait(false);
-        _modelIdToModelVariant.TryGetValue(modelId, out ModelVariant? modelVariant);
+        ModelVariant? modelVariant;
+        using (var disposable = await _lock.LockAsync().ConfigureAwait(false))
+        {
+            _modelIdToModelVariant.TryGetValue(modelId, out modelVariant);
+        }
+        if (modelVariant is not null)
+        {
+            return modelVariant;
+        }
+
+        // Self-heal: the id may belong to a BYOM model added to the cache
+        // directory after our last catalog refresh.
+        await UpdateModels(ct, force: true).ConfigureAwait(false);
+        using (var disposable = await _lock.LockAsync().ConfigureAwait(false))
+        {
+            _modelIdToModelVariant.TryGetValue(modelId, out modelVariant);
+        }
         return modelVariant;
     }
 
@@ -190,10 +252,13 @@ private async Task<IModel> GetLatestVersionImplAsync(IModel modelOrModelVariant,
         return latest.Id == modelOrModelVariant.Id ? modelOrModelVariant : latest;
     }
 
-    private async Task UpdateModels(CancellationToken? ct)
+    private async Task UpdateModels(CancellationToken? ct, bool force = false)
     {
         // TODO: make this configurable
-        if (DateTime.Now - _lastFetch < TimeSpan.FromHours(6))
+        // Skip if the cache is still fresh, unless the caller forced a refresh
+        // (e.g. self-heal after a cache miss caused by a manually-added BYOM
+        // model dropped into the cache directory).
+        if (!force && DateTime.Now - _lastFetch < TimeSpan.FromHours(6))
         {
             return;
         }
@@ -215,26 +280,64 @@ private async Task UpdateModels(CancellationToken? ct)
 
         using var disposable = await _lock.LockAsync().ConfigureAwait(false);
 
-        // TODO: Do we need to clear this out, or can we just add new models?
-        _modelAliasToModel.Clear();
-        _modelIdToModelVariant.Clear();
+        // Incremental refresh: preserve wrapper identity for ids/aliases that
+        // survive the refresh so externally-held IModel references keep
+        // working with up-to-date metadata and (for Model) keep any explicit
+        // SelectVariant() choice. New ids get fresh wrappers; removed ids get
+        // evicted.
+
+        var freshIds = new HashSet<string>(StringComparer.Ordinal);
+        var freshAliasGroups = new Dictionary<string, List<ModelInfo>>(StringComparer.Ordinal);
+        foreach (var info in models)
+        {
+            freshIds.Add(info.Id);
+            if (!freshAliasGroups.TryGetValue(info.Alias, out var group))
+            {
+                group = [];
+                freshAliasGroups[info.Alias] = group;
+            }
+            group.Add(info);
+        }
 
-        foreach (var modelInfo in models)
+        foreach (var staleId in _modelIdToModelVariant.Keys.Where(id => !freshIds.Contains(id)).ToList())
         {
-            var variant = new ModelVariant(modelInfo, _modelLoadManager, _coreInterop, _logger);
+            _modelIdToModelVariant.Remove(staleId);
+        }
+        foreach (var staleAlias in _modelAliasToModel.Keys.Where(a => !freshAliasGroups.ContainsKey(a)).ToList())
+        {
+            _modelAliasToModel.Remove(staleAlias);
+        }
 
-            var existingModel = _modelAliasToModel.TryGetValue(modelInfo.Alias, out Model? value);
-            if (!existingModel)
+        foreach (var info in models)
+        {
+            if (_modelIdToModelVariant.TryGetValue(info.Id, out var existing))
             {
-                value = new Model(variant, _logger);
-                _modelAliasToModel[modelInfo.Alias] = value;
+                existing.RefreshInfo(info);
             }
             else
             {
-                value!.AddVariant(variant);
+                _modelIdToModelVariant[info.Id] = new ModelVariant(info, _modelLoadManager, _coreInterop, _logger);
             }
+        }
 
-            _modelIdToModelVariant[variant.Id] = variant;
+        foreach (var kvp in freshAliasGroups)
+        {
+            var alias = kvp.Key;
+            var aliasInfos = kvp.Value;
+            var aliasVariants = aliasInfos.ConvertAll(i => _modelIdToModelVariant[i.Id]);
+            if (_modelAliasToModel.TryGetValue(alias, out var existingModel))
+            {
+                existingModel.RefreshVariants(aliasVariants);
+            }
+            else
+            {
+                var m = new Model(aliasVariants[0], _logger);
+                for (var i = 1; i < aliasVariants.Count; i++)
+                {
+                    m.AddVariant(aliasVariants[i]);
+                }
+                _modelAliasToModel[alias] = m;
+            }
         }
 
         _lastFetch = DateTime.Now;
 
@@ -12,7 +12,7 @@ public class Model : IModel
 {
     private readonly ILogger _logger;
 
-    private readonly List<IModel> _variants;
+    private List<IModel> _variants;
     public IReadOnlyList<IModel> Variants => _variants;
     internal IModel SelectedVariant { get; set; } = default!;
 
@@ -50,7 +50,9 @@ internal void AddVariant(ModelVariant variant)
                                             _logger);
         }
 
-        _variants.Add(variant);
+        // Build a fresh list and swap by reference so concurrent readers of
+        // Variants never observe a torn collection mid-mutation.
+        _variants = [.. _variants, variant];
 
         // prefer the highest priority locally cached variant
         if (variant.Info.Cached && !SelectedVariant.Info.Cached)
@@ -59,6 +61,35 @@ internal void AddVariant(ModelVariant variant)
         }
     }
 
+    /// <summary>
+    /// Replace the variant list in place while preserving wrapper identity.
+    /// Called by <see cref="Catalog.UpdateModels"/> during incremental
+    /// refresh so a user's held <see cref="Model"/> reference keeps pointing
+    /// at the same object across refreshes. Because
+    /// <see cref="Catalog.UpdateModels"/> reuses the same
+    /// <see cref="ModelVariant"/> wrappers for ids that survive a refresh,
+    /// any explicit <see cref="SelectVariant"/> choice that survives the
+    /// refresh is preserved without any extra work here.
+    ///
+    /// We swap the backing list by reference rather than mutating it so
+    /// readers iterating <see cref="Variants"/> on another thread cannot
+    /// observe a torn collection.
+    /// </summary>
+    // TODO: tighten the held-reference contract for the case where the
+    // previously selected variant is removed by a refresh; today
+    // SelectedVariant keeps pointing at the dropped wrapper and callers must
+    // explicitly re-select.
+    internal void RefreshVariants(IList<ModelVariant> variants)
+    {
+        if (variants == null || variants.Count == 0)
+        {
+            throw new FoundryLocalException(
+                $"Cannot refresh model {Alias} with an empty variant list", _logger);
+        }
+
+        _variants = [.. variants];
+    }
+
     /// <summary>
     /// Select a specific model variant from <see cref="Variants"/> to use for <see cref="IModel"/> operations.
     /// </summary>
 
@@ -17,12 +17,12 @@ internal class ModelVariant : IModel
     private readonly ICoreInterop _coreInterop;
     private readonly ILogger _logger;
 
-    public ModelInfo Info { get; } // expose the full info record
+    public ModelInfo Info { get; private set; } // expose the full info record
 
     // expose a few common properties directly
     public string Id => Info.Id;
     public string Alias => Info.Alias;
-    public int Version { get; init; }  // parsed from Info.Version if possible, else 0
+    public int Version { get; private set; }  // parsed from Info.Version if possible, else 0
 
     public IReadOnlyList<IModel> Variants => [this];
 
@@ -38,6 +38,23 @@ internal ModelVariant(ModelInfo modelInfo, IModelLoadManager modelLoadManager, I
 
     }
 
+    /// <summary>
+    /// Replace the cached <see cref="ModelInfo"/> snapshot in place.
+    /// Called by <see cref="Catalog.UpdateModels"/> during incremental refresh
+    /// so wrapper identity is preserved across refreshes while still surfacing
+    /// fresh metadata (notably <c>Cached</c>) on held references. <c>Id</c>
+    /// and <c>Alias</c> are immutable for a given variant; callers must only
+    /// invoke this with a <paramref name="modelInfo"/> whose id matches
+    /// <see cref="Id"/>. Reference assignment in CLR is atomic, so concurrent
+    /// readers observe either the old or new snapshot, never a torn
+    /// intermediate.
+    /// </summary>
+    internal void RefreshInfo(ModelInfo modelInfo)
+    {
+        Info = modelInfo;
+        Version = modelInfo.Version;
+    }
+
     // simpler and always correct to check if loaded from the model load manager
     // this allows for multiple instances of ModelVariant to exist
     public async Task<bool> IsLoadedAsync(CancellationToken? ct = null)