fix(brain): context, brain_get and brain_read read through brainfs (#157, slice 2) (#165)

readExcerpt, ReadNote and ReadScoped now read through brainfs (os.Root, regular files only, type checked on the opened handle), so a symlink swapped in after a check is not followed and a FIFO does not hang the reader. ReadRegularMax bounds the read itself with io.LimitReader(max+1). notes.Target carries the brain root.

Refs #157. Adversarial review round 2: PASS (round 1 BLOCKED: unbounded read, rule-9 test names).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: Mathias <mthbqv@gmail.com>

ingestion/internal/brainfs/brainfstest/brainfstest.go

@@ -0,0 +1,103 @@
+// Package brainfstest is the shared harness for hyperguild#157's swap-race
+// tests: it keeps swapping a regular note, a symlink to an outside file, or a
+// FIFO (with a writer held open) into a path while a reader under test loops.
+// It observes two things: no sentinel byte from the outside file reaches the
+// reader's output, and the reader returns within a timeout. It does not cover
+// hard links, other paths into the reader, or races it does not generate.
+package brainfstest
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"syscall"
+	"testing"
+	"time"
+)
+
+// Sentinel marks the outside file's contents.
+const Sentinel = "zqbrainfssentinelonefiftyseven"
+
+// Outside writes a file outside any brain dir containing Sentinel.
+func Outside(t *testing.T) string {
+	t.Helper()
+	p := filepath.Join(t.TempDir(), "secret.md")
+	if err := os.WriteFile(p, []byte("# secret\n\n"+Sentinel), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	return p
+}
+
+// StartSwap renames, in a loop, a regular note (content inside) and either
+// a symlink to outside or a FIFO into path, until the test ends. FIFOs get a
+// writer held open until the swapper exits, so a reader that skips the
+// handle check parks forever instead of reading EOF. The swapper is stopped
+// and awaited before t.TempDir cleanup.
+func StartSwap(t *testing.T, path, inside, outside string, fifo bool) {
+	t.Helper()
+	var stop atomic.Bool
+	var wg sync.WaitGroup
+	wg.Add(1)
+	go func() {
+		defer wg.Done()
+		tmp := path + ".swap"
+		var writers []*os.File
+		defer func() {
+			for _, w := range writers {
+				_ = w.Close()
+			}
+		}()
+		for i := 0; !stop.Load(); i++ {
+			_ = os.Remove(tmp)
+			switch {
+			case i%2 == 0:
+				_ = os.WriteFile(tmp, []byte(inside), 0o644)
+			case fifo:
+				if err := syscall.Mkfifo(tmp, 0o644); err == nil {
+					if w, err := os.OpenFile(tmp, os.O_RDWR, 0); err == nil {
+						writers = append(writers, w)
+					}
+				}
+			default:
+				_ = os.Symlink(outside, tmp)
+			}
+			_ = os.Rename(tmp, path)
+		}
+	}()
+	t.Cleanup(func() { stop.Store(true); wg.Wait() })
+}
+
+// AssertNoLeak loops read for d while a symlink swapper runs on path, and
+// fails if any output contains Sentinel.
+func AssertNoLeak(t *testing.T, path, inside string, d time.Duration, read func() string) {
+	t.Helper()
+	StartSwap(t, path, inside, Outside(t), false)
+	leaks, iters := 0, 0
+	for deadline := time.Now().Add(d); time.Now().Before(deadline); iters++ {
+		leaks += strings.Count(read(), Sentinel)
+	}
+	if leaks > 0 {
+		t.Fatalf("outside file leaked %d times in %d iterations", leaks, iters)
+	}
+}
+
+// AssertNoHang loops read for d while a FIFO swapper (held writers) runs on
+// path, and fails if a read does not return within timeout.
+func AssertNoHang(t *testing.T, path, inside string, d, timeout time.Duration, read func()) {
+	t.Helper()
+	StartSwap(t, path, inside, Outside(t), true)
+	done := make(chan struct{})
+	go func() {
+		for deadline := time.Now().Add(d); time.Now().Before(deadline); {
+			read()
+		}
+		close(done)
+	}()
+	select {
+	case <-done:
+	case <-time.After(timeout):
+		t.Fatal("reader hung on a swapped-in FIFO with a writer held open")
+	}
+}