Eliminate shared mutable builtin virtual FS state in parser registration path

pkg/parser/spec_test.go

@@ -710,6 +710,25 @@ func TestSpec_VirtualFilesystem_RegisterBuiltinVirtualFile(t *testing.T) {
 		assert.False(t, BuiltinVirtualFileExists(path),
 			"BuiltinVirtualFileExists should return false for paths that were never registered")
 	})
+
+	t.Run("registered content is stable if caller mutates input slice", func(t *testing.T) {
+		path := "@builtin:spec-test-content-copy-" + t.Name()
+		content := []byte("immutable builtin content")
+
+		RegisterBuiltinVirtualFile(path, content)
+		content[0] = 'X'
+
+		readContent, err := ReadFile(path)
+		require.NoError(t, err, "ReadFile should resolve registered builtin path")
+		assert.Equal(t, []byte("immutable builtin content"), readContent,
+			"builtin virtual file content should not change when caller mutates source slice")
+
+		readContent[0] = 'X'
+		readContent, err = ReadFile(path)
+		require.NoError(t, err, "ReadFile should resolve registered builtin path")
+		assert.Equal(t, []byte("immutable builtin content"), readContent,
+			"builtin virtual file content should not change when caller mutates read data")
+	})
 }
 
 // TestSpec_PublicAPI_FindClosestMatches validates the documented behavior of

pkg/parser/virtual_fs.go

@@ -3,6 +3,7 @@ package parser
 import (
 	"bytes"
 	"fmt"
+	"maps"
 	"os"
 	"strings"
 	"sync"
@@ -14,7 +15,8 @@ var virtualFsLog = logger.New("parser:virtual_fs")
 
 // builtinVirtualFiles holds embedded built-in files registered at startup.
 // Keys use the "@builtin:" path prefix (e.g. "@builtin:engines/copilot.md").
-// The map is populated once and then read-only; concurrent reads are safe.
+// The map is replaced using copy-on-write during registration and then treated
+// as read-only; concurrent reads are safe.
 var (
 	builtinVirtualFiles   map[string][]byte
 	builtinVirtualFilesMu sync.RWMutex
@@ -31,17 +33,17 @@ func RegisterBuiltinVirtualFile(path string, content []byte) {
 	}
 	builtinVirtualFilesMu.Lock()
 	defer builtinVirtualFilesMu.Unlock()
-	if builtinVirtualFiles == nil {
-		builtinVirtualFiles = make(map[string][]byte)
-	}
 	if existing, ok := builtinVirtualFiles[path]; ok {
 		if !bytes.Equal(existing, content) {
 			panic(fmt.Sprintf("RegisterBuiltinVirtualFile: path %q already registered with different content", path))
 		}
 		return // idempotent: same content, no-op
 	}
 	virtualFsLog.Printf("Registering builtin virtual file: %s (%d bytes)", path, len(content))
-	builtinVirtualFiles[path] = content
+	next := make(map[string][]byte, len(builtinVirtualFiles)+1)
+	maps.Copy(next, builtinVirtualFiles)
+	next[path] = bytes.Clone(content)
+	builtinVirtualFiles = next
 }
 
 // BuiltinVirtualFileExists returns true if the given path is registered as a builtin virtual file.
@@ -116,7 +118,7 @@ var readFileFunc = func(path string) ([]byte, error) {
 	defer builtinVirtualFilesMu.RUnlock()
 	content, ok := builtinVirtualFiles[path]
 	if ok {
-		return content, nil
+		return bytes.Clone(content), nil
 	}
 	return os.ReadFile(path)
 }