fix(multiapp): serve ReadAt from a detached handle on cache eviction race

embedded/appendable/multiapp/appendable_cache.go

@@ -91,6 +91,19 @@ func (r *refCountedApp) Close() error {
 	return nil
 }
 
+// newDetachedApp wraps an appendable that lives *outside* the cache and
+// is handed to a single reader which must Release() it exactly once. It
+// starts already-evicted with one ref, so that Release performs the
+// underlying Close — there is no cache entry to govern its lifetime.
+//
+// Used as a fallback when a freshly-opened chunk is evicted (or
+// replaced) by a concurrent insert before the foreground reader can
+// take its ref: rather than fail the read with a spurious
+// `key not found`, the reader is served from this detached handle.
+func newDetachedApp(value appendable.Appendable) *refCountedApp {
+	return &refCountedApp{Appendable: value, refs: 1, evicted: true}
+}
+
 type appendableCache struct {
 	cache *cache.Cache
 }

embedded/appendable/multiapp/multi_app.go

@@ -646,19 +646,34 @@ func (mf *MultiFileAppendable) appendableFor(off int64) (appendable.Appendable,
 	}
 
 	mf.mutex.Lock()
-	defer mf.mutex.Unlock()
 
 	if mf.closed {
+		mf.mutex.Unlock()
 		return nil, ErrAlreadyClosed
 	}
 
 	app, err := mf.appendables.Get(appID)
-	if err != nil {
+	if err == nil {
+		mf.maybePrefetchAheadLocked(appID)
+		mf.mutex.Unlock()
+		return app, nil
+	}
+	mf.mutex.Unlock()
+
+	if !errors.Is(err, cache.ErrKeyNotFound) {
 		return nil, err
 	}
 
-	mf.maybePrefetchAheadLocked(appID)
-	return app, nil
+	// The chunk was opened and cached by the singleflight above, but a
+	// concurrent insert (foreground miss or background prefetch) evicted
+	// or replaced it before we could take our ref. The data is still
+	// readable — re-open a detached, self-closing handle for this read
+	// rather than surfacing a spurious ErrKeyNotFound to the caller.
+	raw, err := mf.openAppendableFromSnapshot(snap, appendableName(appID, mf.fileExt), false, false)
+	if err != nil {
+		return nil, err
+	}
+	return newDetachedApp(raw), nil
 }
 
 // openAppendableSnapshot is a snapshot of the bits that openAppendable

embedded/appendable/multiapp/multi_app_prefetch_race_test.go

@@ -0,0 +1,91 @@
+/*
+Copyright 2026 Codenotary Inc. All rights reserved.
+
+SPDX-License-Identifier: BUSL-1.1
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    https://mariadb.com/bsl11/
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package multiapp
+
+import (
+	"fmt"
+	"sync"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+// TestMultiAppConcurrentReadEvictionRace exercises the read path under a
+// cache too small to hold the working set while background prefetch is
+// active. A foreground cache-miss opens and caches a chunk, then has to
+// re-acquire it from the cache; a concurrent prefetch insert can evict
+// that just-inserted entry in between, which previously surfaced as a
+// spurious "key not found" error from ReadAt for a perfectly valid
+// offset. The read must always succeed and return the correct bytes.
+func TestMultiAppConcurrentReadEvictionRace(t *testing.T) {
+	const (
+		fileSize  = 8
+		numChunks = 32
+		total     = fileSize * numChunks
+	)
+
+	a, err := Open(t.TempDir(),
+		DefaultOptions().
+			WithFileSize(fileSize).
+			WithMaxOpenedFiles(2).
+			WithPrefetchAheadDepth(4),
+	)
+	require.NoError(t, err)
+
+	data := make([]byte, total)
+	for i := range data {
+		data[i] = byte(i)
+	}
+
+	_, _, err = a.Append(data)
+	require.NoError(t, err)
+	require.NoError(t, a.Flush())
+
+	const readers = 16
+	var wg sync.WaitGroup
+	errCh := make(chan error, readers)
+
+	for g := 0; g < readers; g++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			buf := make([]byte, 1)
+			for rep := 0; rep < 8; rep++ {
+				// Sequential scan triggers prefetch-ahead.
+				for off := int64(0); off < total; off++ {
+					n, rerr := a.ReadAt(buf, off)
+					if rerr != nil {
+						errCh <- rerr
+						return
+					}
+					if n != 1 || buf[0] != byte(off) {
+						errCh <- fmt.Errorf("offset %d: read %d bytes = %v, want byte %d", off, n, buf[:n], byte(off))
+						return
+					}
+				}
+			}
+		}()
+	}
+
+	wg.Wait()
+	close(errCh)
+	for rerr := range errCh {
+		require.NoError(t, rerr)
+	}
+
+	require.NoError(t, a.Close())
+}