fix: invalidate VFS existence cache when refreshing metadata

Author: KSemenenko

Directory.Build.props

@@ -29,8 +29,8 @@
         <RepositoryUrl>https://github.com/managedcode/Storage</RepositoryUrl>
         <PackageProjectUrl>https://github.com/managedcode/Storage</PackageProjectUrl>
         <Product>Managed Code - Storage</Product>
-        <Version>10.1.0</Version>
-        <PackageVersion>10.1.0</PackageVersion>
+        <Version>10.1.1</Version>
+        <PackageVersion>10.1.1</PackageVersion>
 
     </PropertyGroup>
 

ManagedCode.Storage.VirtualFileSystem/Implementations/VirtualFile.cs

@@ -98,6 +98,7 @@ public async Task RefreshAsync(CancellationToken cancellationToken = default)
 
         if (_vfs.Options.EnableCache)
         {
+            _cache.Remove($"file_exists:{_vfs.ContainerName}:{_path}");
             var metadataKey = $"file_metadata:{_vfs.ContainerName}:{_path}";
             var entry = new MetadataCacheEntry
             {

Tests/ManagedCode.Storage.Tests/VirtualFileSystem/VfsImmutableMetadataTests.cs

@@ -95,6 +95,49 @@ await storage.RequireObjectStorage().WriteObjectAsync("legacy/content", bytes,
         });
     }
 
+    [Theory]
+    [InlineData(false)]
+    [InlineData(true)]
+    public async Task Refresh_AfterMultipartCommit_ExposesCommittedBytes(bool cache)
+    {
+        await using var provider = CreateProvider(cache);
+        await using var scope = provider.CreateAsyncScope();
+        var vfs = scope.ServiceProvider.GetRequiredService<IVirtualFileSystem>();
+        var path = new VfsPath("/learning/commands/output.zip");
+        var file = await vfs.GetFileAsync(path);
+        (await file.ExistsAsync()).ShouldBeFalse();
+        await file.RefreshAsync();
+        var bytes = Encoding.UTF8.GetBytes("committed archive bytes");
+        var multipart = vfs.Storage.RequireMultipartStorage();
+        await multipart.CreatePrivateContainerAsync();
+        var partId = Convert.ToBase64String(Encoding.UTF8.GetBytes("archive-part-0001"));
+        using var part = new MemoryStream(bytes);
+        await multipart.StagePartAsync(path.ToBlobKey(), partId, part);
+        await multipart.CommitPartsAsync(path.ToBlobKey(), [partId]);
+        await file.RefreshAsync();
+        file.Size.ShouldBe(bytes.LongLength);
+        (await file.ExistsAsync()).ShouldBeTrue();
+        (await file.ReadAllBytesAsync()).ShouldBe(bytes);
+    }
+
+    [Theory]
+    [InlineData(false)]
+    [InlineData(true)]
+    public async Task Refresh_AfterProviderDeletion_ReportsMissingFile(bool cache)
+    {
+        await using var provider = CreateProvider(cache);
+        await using var scope = provider.CreateAsyncScope();
+        var vfs = scope.ServiceProvider.GetRequiredService<IVirtualFileSystem>();
+        var path = new VfsPath("/learning/commands/deleted.zip");
+        var file = await vfs.GetFileAsync(path);
+        await file.WriteAllBytesAsync(Encoding.UTF8.GetBytes("previous archive bytes"));
+        (await file.ExistsAsync()).ShouldBeTrue();
+        (await vfs.Storage.RequireObjectStorage().DeleteObjectIfExistsAsync(path.ToBlobKey())).ShouldBeTrue();
+        await file.RefreshAsync();
+        file.Size.ShouldBe(0);
+        (await file.ExistsAsync()).ShouldBeFalse();
+    }
+
     private ServiceProvider CreateProvider(bool cache)
     {
         var services = new ServiceCollection();

docs/Architecture.md

@@ -50,6 +50,7 @@ versioned ASCII envelope decoded across all metadata reads. See the
 [Azure provider](Features/provider-azure-blob.md#metadata-transport) for its
 physical representation, collision handling and metadata-size constraints.
 VFS writes persist zero-byte files and truncate existing files on empty overwrite.
+`IVirtualFile.RefreshAsync` invalidates cached existence after refreshing provider metadata, so externally committed or deleted objects are visible to subsequent existence checks and reads.
 `FileExistsAsync` remains a cached, best-effort convenience query. Consumers that
 make conflict, authorization, or recovery decisions use
 `IVirtualFileSystem.StorageFileExistsAsync`, which reads the backing provider and

docs/Features/virtual-file-system.md

@@ -18,6 +18,8 @@ This is *not* a separate cloud provider. It is an abstraction layer that sits ab
 
 ### File operations
 
+After a write or deletion through the backing provider, call `IVirtualFile.RefreshAsync` on an existing file handle. It refreshes metadata and invalidates cached existence, including a cached miss before a multipart commit. The next existence check and read observe the committed object.
+
 ```mermaid
 flowchart TD
   A[Caller] --> VFS[IVirtualFileSystem]