fix: perpetual shader recompile from zero-hash cache entries

Consume SuppressSourceHash on the cache-hit path so it can no longer leak
into the next compiled shader and strip its OpSourceHashSDSL. A stripped
hash read back as zero, making EffectCompilerCache.IsBytecodeObsolete
recompile every run.

Also stamp a format version into the cached .spv header (Generator id +
Schema) and reject mismatches on load, so already-poisoned cache files are
recompiled and overwritten instead of served stale.

Author: xen2

sources/shaders/Stride.Shaders.Compilers/FileShaderCache.cs

@@ -9,6 +9,7 @@
 using Stride.Shaders.Spirv.Building;
 using Stride.Shaders.Spirv.Core;
 using Stride.Shaders.Spirv.Core.Buffers;
+using Stride.Shaders.Spirv.Core.Parsing;
 
 namespace Stride.Shaders.Compilers;
 
@@ -27,6 +28,12 @@ public class FileShaderCache(IVirtualFileProvider fileProvider, string basePath
     private readonly object lockObject = new();
     private readonly ShaderCache memoryCache = new();
 
+    // Cache files are stamped in the SPIR-V header: Generator identifies our shader cache, Schema is the
+    // format version. A mismatch (including old 0/0 headers) is treated as stale and forces a recompile,
+    // which overwrites the file in place. Bump CacheFormatVersion on any incompatible .spv cache change.
+    private const int ShaderCacheGeneratorId = 0x5344534C; // 'SDSL'
+    private const int CacheFormatVersion = 1;
+
     public bool Exists(string name)
     {
         if (memoryCache.Exists(name))
@@ -87,7 +94,14 @@ public bool TryLoadFromCache(string name, string? generics, ReadOnlySpan<ShaderM
 
                 using var stream = fileProvider.OpenStream(path, VirtualFileMode.Open, VirtualFileAccess.Read);
                 using var reader = new BinaryReader(stream);
-                buffer = Deserialize(reader, out hash);
+                if (!TryDeserialize(reader, out buffer, out hash))
+                {
+                    // Stale/incompatible cache file (old or missing version stamp): treat it like a
+                    // cache miss so the caller recompiles and overwrites it in place.
+                    buffer = default;
+                    hash = default;
+                    return false;
+                }
             }
 
             // Populate in-memory cache for subsequent lookups
@@ -142,19 +156,35 @@ private static string ComputeCacheFilename(string? generics, ReadOnlySpan<Shader
 
     private static void Serialize(BinaryWriter writer, ShaderBuffers buffers, ObjectId hash)
     {
-        var bytecode = SpirvBytecode.CreateBytecodeFromBuffers(buffers.Context.GetBuffer(), buffers.Buffer);
+        var header = new SpirvHeader("1.4", generator: ShaderCacheGeneratorId, bound: 1, schema: CacheFormatVersion);
+        var bytecode = SpirvBytecode.CreateBytecodeFromBuffers(header, computeBounds: true, buffers.Context.GetBuffer(), buffers.Buffer);
         writer.Write(bytecode);
     }
 
-    private ShaderBuffers Deserialize(BinaryReader reader, out ObjectId hash)
+    /// <summary>
+    /// Reads a cached buffer. Returns false (a plain cache miss) when the file predates the current
+    /// cache format — an old or absent version stamp is expected, not corruption. Genuinely malformed
+    /// content still throws, so callers can distinguish it.
+    /// </summary>
+    private bool TryDeserialize(BinaryReader reader, [MaybeNullWhen(false)] out ShaderBuffers result, out ObjectId hash)
     {
+        result = default;
+        hash = default;
+
         var buffer = new byte[reader.BaseStream.Length];
         reader.ReadExactly(buffer);
+        var span = buffer.AsSpan().Cast<byte, int>();
 
-        var result = ShaderBuffers.CreateFromSpan(buffer.AsSpan().Cast<byte, int>());
+        if (span.Length < SpirvHeader.IntSpanSize)
+            return false;
+
+        var header = SpirvHeader.Read(span);
+        if (header.Generator != ShaderCacheGeneratorId || header.Schema != CacheFormatVersion)
+            return false;
+
+        result = ShaderBuffers.CreateFromSpan(span);
 
         // Fetch hash from OpSourceHashSDSL
-        hash = default;
         foreach (var i in result.Context)
         {
             if (i.Op == Spirv.Specification.Op.OpSourceHashSDSL && (OpSourceHashSDSL)i is { } sourceHash)
@@ -166,7 +196,7 @@ private ShaderBuffers Deserialize(BinaryReader reader, out ObjectId hash)
 
         ShaderClass.ProcessNameAndTypes(result.Context, ShaderImporter);
 
-        return result;
+        return true;
     }
 
     private static int GetTotalWordCount(SpirvBuffer buffer)

sources/shaders/Stride.Shaders.Compilers/SDSL/ShaderMixer.cs

@@ -1377,6 +1377,10 @@ public bool LoadExternalFileContent(string name, out string filename, out string
     public bool LoadExternalBuffer(string name, ReadOnlySpan<ShaderMacro> defines, out ShaderBuffers bytecode, out ObjectId hash, out bool isFromCache)
     {
         var result = inner.LoadExternalBuffer(name, defines, out bytecode, out hash, out isFromCache);
+        // A file-backed shader always carries a source hash. A zero here means it was compiled or cached
+        // without its OpSourceHashSDSL, which would make its effect obsolete (recompiled) on every run.
+        if (hash == ObjectId.Empty)
+            throw new InvalidOperationException($"Shader '{name}' was loaded without a source hash (missing OpSourceHashSDSL).");
         if (!Sources.ContainsKey(name))
             Sources.Add(name, hash);
         return result;

sources/shaders/Stride.Shaders.Compilers/ShaderLoaderBase.cs

@@ -96,13 +96,19 @@ public bool LoadExternalBuffer(string name, ReadOnlySpan<ShaderMacro> defines, [
 
     public bool LoadExternalBuffer(string name, string? filename, string code, ReadOnlySpan<ShaderMacro> defines, [MaybeNullWhen(false)] out ShaderBuffers buffer, out ObjectId hash, out bool isFromCache)
     {
+        // Consume the one-shot suppress flag now, before any early return, so it can't leak into a
+        // later compilation when this load is served from the cache. A leaked flag would strip that
+        // shader's OpSourceHashSDSL, making its cached source hash read back as zero.
+        var emitSourceHash = !SuppressSourceHash;
+        SuppressSourceHash = false;
+
         isFromCache = Cache.TryLoadFromCache(name, null, defines, out buffer, out hash);
         if (isFromCache)
             return true;
 
         hash = ObjectId.FromBytes(Encoding.UTF8.GetBytes(code));
         // Don't auto-register in SDSLC — the caller (InstantiateMemberNames) registers under the cache key
-        if (!LoadFromCode(filename, code, hash, defines, out buffer, registerInCache: false))
+        if (!LoadFromCode(filename, code, hash, defines, out buffer, registerInCache: false, emitSourceHash: emitSourceHash))
         {
             // If a logger is set, errors are already logged — just return false
             if (Log != null)
@@ -162,7 +168,7 @@ private static int ComputeMacrosHash(ReadOnlySpan<ShaderMacro> macros)
         }
     }
 
-    protected virtual bool LoadFromCode(string? filename, string code, ObjectId hash, ReadOnlySpan<ShaderMacro> macros, out ShaderBuffers buffer, bool registerInCache = true)
+    protected virtual bool LoadFromCode(string? filename, string code, ObjectId hash, ReadOnlySpan<ShaderMacro> macros, out ShaderBuffers buffer, bool registerInCache = true, bool emitSourceHash = true)
     {
         var defines = new (string Name, string Definition)[macros.Length];
         for (int i = 0; i < macros.Length; ++i)
@@ -176,8 +182,6 @@ protected virtual bool LoadFromCode(string? filename, string code, ObjectId hash
 
         // Use provided logger, or a temporary one that throws on errors
         var log = Log ?? new LoggerResult();
-        var emitSourceHash = !SuppressSourceHash;
-        SuppressSourceHash = false; // Reset after use
         if (!sdslc.Compile(filename, text, hash, macros, log, out buffer, new() { RegisterInCache = registerInCache, EmitSourceHash = emitSourceHash, OriginalCode = code }))
         {
             if (log is LoggerResult loggerResult && loggerResult.HasErrors)

sources/shaders/Stride.Shaders.Tests/ShaderLoader.cs

@@ -43,9 +43,9 @@ public override bool LoadExternalFileContent(string name, out string filename, o
         return false;
     }
 
-    protected override bool LoadFromCode(string? filename, string code, ObjectId hash, ReadOnlySpan<ShaderMacro> macros, out ShaderBuffers buffer, bool registerInCache = true)
+    protected override bool LoadFromCode(string? filename, string code, ObjectId hash, ReadOnlySpan<ShaderMacro> macros, out ShaderBuffers buffer, bool registerInCache = true, bool emitSourceHash = true)
     {
-        var result = base.LoadFromCode(filename, code, hash, macros, out buffer, registerInCache);
+        var result = base.LoadFromCode(filename, code, hash, macros, out buffer, registerInCache, emitSourceHash);
         if (result)
         {
             Console.WriteLine($"Loading shader {filename}");

sources/shaders/Stride.Shaders.Tests/StrideShaderTests.cs

@@ -1,11 +1,15 @@
 using System;
 using System.Collections.Generic;
+using System.IO;
 using System.Text;
 using CommunityToolkit.HighPerformance;
 using Silk.NET.SPIRV;
 using Silk.NET.SPIRV.Cross;
+using Stride.Core.IO;
+using Stride.Core.Storage;
 using Stride.Shaders.Compilers;
 using Stride.Shaders.Compilers.SDSL;
+using Stride.Shaders.Spirv.Building;
 using Stride.Shaders.Spirv.Core.Buffers;
 using Stride.Shaders.Spirv.Tools;
 using Spv = Stride.Shaders.Spirv.Tools.Spv;
@@ -14,6 +18,90 @@ namespace Stride.Shaders.Parsers.Tests;
 
 public class StrideShaderTests
 {
+    // Regression: the MemberName re-instantiation path sets ShaderLoaderBase.SuppressSourceHash and
+    // relies on LoadFromCode to clear it. When the load hits the shader cache instead, LoadFromCode
+    // never runs, so the flag leaks into the next compiled shader and strips its OpSourceHashSDSL.
+    // A cached shader without OpSourceHashSDSL deserializes to a zero hash, which makes
+    // EffectCompilerCache.IsBytecodeObsolete return true on every run (a permanent recompile hang).
+    [Fact]
+    public void SuppressSourceHashDoesNotLeakAcrossCacheHits()
+    {
+        var loader = new ShaderLoader("./assets/Stride/SDSL");
+
+        // Warm the cache: a normally compiled shader carries its OpSourceHashSDSL.
+        Assert.True(loader.LoadExternalBuffer("Texturing", [], out var texturing, out _, out _));
+        Assert.True(HasSourceHash(texturing), "sanity: a normally compiled shader carries OpSourceHashSDSL");
+
+        // Reproduce the MemberName path (Builder.Class.InstantiateMemberNames): set the flag, then load
+        // a shader that is already cached. The (name, filename, code) overload returns on the cache hit
+        // before LoadFromCode runs, so the flag is never cleared.
+        Assert.True(loader.LoadExternalFileContent("Texturing", out var filename, out var code, out _));
+        loader.SuppressSourceHash = true;
+        Assert.True(loader.LoadExternalBuffer("Texturing", filename, code, [], out _, out _, out var isFromCache));
+        Assert.True(isFromCache, "precondition: the second load must be a cache hit to exercise the leak");
+
+        Assert.False(loader.SuppressSourceHash,
+            "SuppressSourceHash leaked past a cache hit; the next compiled shader would be cached without " +
+            "OpSourceHashSDSL (zero hash => EffectCompilerCache recompiles every run)");
+
+        // Downstream symptom: with the flag leaked, the next freshly compiled shader loses its hash.
+        Assert.True(loader.LoadExternalBuffer("ShaderBase", [], out var shaderBase, out _, out _));
+        Assert.True(HasSourceHash(shaderBase),
+            "the next compiled shader is missing OpSourceHashSDSL — its cached hash would deserialize to zero");
+    }
+
+    private static bool HasSourceHash(ShaderBuffers buffer)
+    {
+        foreach (var i in buffer.Context)
+        {
+            if (i.Op == Stride.Shaders.Spirv.Specification.Op.OpSourceHashSDSL)
+                return true;
+        }
+        return false;
+    }
+
+    // FileShaderCache stamps a Generator id + Schema (format version) into the SPIR-V header of each
+    // cached .spv. A cached buffer round-trips (including its OpSourceHashSDSL), and a header whose
+    // version no longer matches is rejected so the shader recompiles instead of being served stale.
+    [Fact]
+    public void FileShaderCacheRoundTripsAndRejectsStaleVersion()
+    {
+        var loader = new ShaderLoader("./assets/Stride/SDSL");
+        Assert.True(loader.LoadExternalBuffer("Texturing", [], out var buffer, out var hash, out _));
+        Assert.NotEqual(ObjectId.Empty, hash);
+
+        var tempDir = Directory.CreateTempSubdirectory("stride-shadercache-test");
+        try
+        {
+            var provider = new FileSystemProvider("/testcache", tempDir.FullName);
+            const string spvPath = "shaders/Texturing_default.spv";
+
+            // Write via one instance, read via a fresh instance so the load must come from disk.
+            new FileShaderCache(provider).RegisterShader("Texturing", null, [], buffer, hash);
+
+            Assert.True(new FileShaderCache(provider).TryLoadFromCache("Texturing", null, [], out _, out var loadedHash));
+            Assert.Equal(hash, loadedHash);
+
+            // Corrupt the Schema word (5th header word, byte offset 16) to simulate an old/incompatible cache.
+            byte[] bytes;
+            using (var s = provider.OpenStream(spvPath, VirtualFileMode.Open, VirtualFileAccess.Read))
+            {
+                bytes = new byte[s.Length];
+                s.ReadExactly(bytes);
+            }
+            BitConverter.GetBytes(0x7FFFFFFF).CopyTo(bytes, 16);
+            using (var s = provider.OpenStream(spvPath, VirtualFileMode.Create, VirtualFileAccess.Write))
+                s.Write(bytes);
+
+            Assert.False(new FileShaderCache(provider).TryLoadFromCache("Texturing", null, [], out _, out _),
+                "a cache file with a mismatched format version must be rejected (recompiled), not served stale");
+        }
+        finally
+        {
+            tempDir.Delete(recursive: true);
+        }
+    }
+
     [Fact]
     public void TextureDecorateStringWarning()
     {