fix(vectorstore): walk and read the brain through brainfs (#157, slice 3)

Sync walked wiki/ and knowledge/ with filepath.WalkDir and read each .md
with os.ReadFile. A symlinked note (Syncthing syncs symlinks) had its
target embedded into pgvector and served by semantic search; a FIFO
stalled the sync. The walk and read now go through brainfs: regular
files only, type checked on the opened handle.

- Chunks already embedded from a symlinked note are deleted on the next
  sync, because the note is no longer seen.
- A walk error still aborts Sync before the delete pass, so an unreadable
  subdir does not delete chunks of files that exist. A missing scan dir
  is skipped as before.
- brainfs gains Lstat, used for the mtime staleness check.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

ingestion/internal/brainfs/brainfs.go

@@ -53,6 +53,12 @@ func (b *Brain) Rel(path string) (string, error) {
 	return filepath.ToSlash(rel), nil
 }
 
+// Lstat stats a brain-relative path through the root without following a
+// final symlink.
+func (b *Brain) Lstat(rel string) (fs.FileInfo, error) {
+	return b.root.Lstat(filepath.ToSlash(rel))
+}
+
 // ReadRegular reads a brain-relative path, refusing anything that is not a
 // regular file, both before the open and on the opened handle.
 func (b *Brain) ReadRegular(rel string) ([]byte, error) {

ingestion/internal/brainfs/brainfs_test.go

@@ -3,6 +3,7 @@ package brainfs
 import (
 	"errors"
 	"io"
+	"io/fs"
 	"os"
 	"path/filepath"
 	"syscall"
@@ -139,3 +140,18 @@ func (c *countingReader) Read(p []byte) (int, error) {
 	c.n += n
 	return n, err
 }
+
+func TestLstatDoesNotFollowSymlinksAndRefusesEscapes(t *testing.T) {
+	dir := t.TempDir()
+	outside := filepath.Join(t.TempDir(), "o.md")
+	require.NoError(t, os.WriteFile(outside, []byte("o"), 0o644))
+	require.NoError(t, os.Symlink(outside, filepath.Join(dir, "l.md")))
+	b, err := Open(dir)
+	require.NoError(t, err)
+	defer func() { _ = b.Close() }()
+	fi, err := b.Lstat("l.md")
+	require.NoError(t, err)
+	assert.Equal(t, fs.ModeSymlink, fi.Mode().Type())
+	_, err = b.Lstat("../" + filepath.Base(filepath.Dir(outside)) + "/o.md")
+	assert.Error(t, err)
+}

ingestion/internal/vectorstore/sync.go

@@ -2,12 +2,15 @@ package vectorstore
 
 import (
 	"context"
+	"errors"
 	"fmt"
+	"io/fs"
 	"log/slog"
-	"os"
-	"path/filepath"
+	"path"
 	"strings"
 	"time"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs"
 )
 
 // Embedder produces dense vectors. The embed package's Client satisfies
@@ -90,31 +93,36 @@ func Sync(ctx context.Context, brainDir string, store Store, embedder Embedder)
 	}
 	seenParents := make(map[string]struct{})
 
-	for _, sub := range scanDirs {
-		root := filepath.Join(brainDir, sub)
-		if _, err := os.Stat(root); os.IsNotExist(err) {
-			continue
-		}
-
-		err = filepath.WalkDir(root, func(path string, d os.DirEntry, err error) error {
+	// Through the brain root, regular files only (hyperguild#157): the brain
+	// is a Syncthing folder, and os.ReadFile followed a synced symlink into
+	// the embeddings and blocked on a FIFO.
+	bfs, err := brainfs.Open(brainDir)
 	if err != nil {
-				return err
+		return res, fmt.Errorf("open brain: %w", err)
 	}
-			if d.IsDir() || !strings.HasSuffix(path, ".md") || d.Name() == "_index.md" {
+	defer func() { _ = bfs.Close() }()
+
+	for _, sub := range scanDirs {
+		var walkErr error
+		onErr := func(rel string, err error) {
+			if rel == sub && errors.Is(err, fs.ErrNotExist) {
+				return
+			}
+			if walkErr == nil {
+				walkErr = fmt.Errorf("%s: %w", rel, err)
+			}
+		}
+		err = bfs.WalkRegular(sub, func(relSlash string) error {
+			if !strings.HasSuffix(relSlash, ".md") || path.Base(relSlash) == "_index.md" {
 				return nil
 			}
-			rel, err := filepath.Rel(brainDir, path)
-			if err != nil {
-				return err
-			}
-			relSlash := filepath.ToSlash(rel)
 			seenParents[relSlash] = struct{}{}
 
 			if ps, ok := parents[relSlash]; ok {
 				// File already has chunks in the store. Re-embed only when
 				// the file has been edited since the oldest chunk was
 				// written. Tolerate clock skew with a sub-second grace.
-				info, statErr := d.Info()
+				info, statErr := bfs.Lstat(relSlash)
 				if statErr != nil {
 					res.Errors = append(res.Errors, fmt.Errorf("stat %s: %w", relSlash, statErr))
 					return nil
@@ -132,7 +140,7 @@ func Sync(ctx context.Context, brainDir string, store Store, embedder Embedder)
 				}
 			}
 
-			content, readErr := os.ReadFile(path)
+			content, readErr := bfs.ReadRegular(relSlash)
 			if readErr != nil {
 				res.Errors = append(res.Errors, fmt.Errorf("read %s: %w", relSlash, readErr))
 				return nil
@@ -151,7 +159,12 @@ func Sync(ctx context.Context, brainDir string, store Store, embedder Embedder)
 				res.Added++
 			}
 			return nil
-		})
+		}, onErr)
+		if err == nil {
+			err = walkErr
+		}
+		// Abort before the delete pass: an incomplete walk would leave
+		// seenParents short and delete chunks of files that still exist.
 		if err != nil {
 			return res, fmt.Errorf("walk %s: %w", sub, err)
 		}

ingestion/internal/vectorstore/sync_root_test.go

@@ -0,0 +1,97 @@
+package vectorstore_test
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs/brainfstest"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/vectorstore"
+)
+
+// recordingEmbedder keeps every text it was asked to embed.
+type recordingEmbedder struct {
+	mu    sync.Mutex
+	texts []string
+}
+
+func (e *recordingEmbedder) Embed(_ context.Context, text string) ([]float32, error) {
+	e.mu.Lock()
+	defer e.mu.Unlock()
+	e.texts = append(e.texts, text)
+	return []float32{1}, nil
+}
+
+func (e *recordingEmbedder) all() string {
+	e.mu.Lock()
+	defer e.mu.Unlock()
+	return strings.Join(e.texts, "\n")
+}
+
+// hyperguild#157 slice 3: Sync walked wiki/ and knowledge/ and read each .md
+// with os.ReadFile, so a symlinked note had its target embedded and served by
+// semantic search, and a FIFO stalled the sync.
+func TestSyncRefusesSymlinksAndSurvivesSwapRaces(t *testing.T) {
+	brain := t.TempDir()
+	writeNote(t, brain, "wiki/w/facts/ok.md", "inside note")
+	require.NoError(t, os.Symlink(brainfstest.Outside(t), filepath.Join(brain, "wiki", "w", "facts", "leak.md")))
+
+	emb := &recordingEmbedder{}
+	store := &stubStore{}
+	_, err := vectorstore.Sync(context.Background(), brain, store, emb)
+	require.NoError(t, err)
+	assert.Contains(t, emb.all(), "inside note", "positive control: the regular note is embedded")
+	assert.NotContains(t, emb.all(), brainfstest.Sentinel)
+	for p := range store.upserts {
+		assert.NotContains(t, p, "leak.md")
+	}
+
+	p := filepath.Join(brain, "knowledge", "r.md")
+	require.NoError(t, os.MkdirAll(filepath.Dir(p), 0o755))
+	sync := func() string {
+		e := &recordingEmbedder{}
+		_, _ = vectorstore.Sync(context.Background(), brain, &stubStore{}, e)
+		return e.all()
+	}
+	brainfstest.AssertNoLeak(t, p, "inside", 1500*time.Millisecond, sync)
+	brainfstest.AssertNoHang(t, p, "inside", 1500*time.Millisecond, 6*time.Second, func() { _ = sync() })
+}
+
+// Chunks embedded from a symlinked note before this fix are deleted: the
+// note is no longer seen, so the delete pass drops its rows.
+func TestSyncDeletesChunksOfASymlinkedNote(t *testing.T) {
+	brain := t.TempDir()
+	writeNote(t, brain, "wiki/w/facts/ok.md", "inside note")
+	require.NoError(t, os.Symlink(brainfstest.Outside(t), filepath.Join(brain, "wiki", "w", "facts", "leak.md")))
+	store := &stubStore{known: map[string]time.Time{
+		"wiki/w/facts/leak.md#0001": {},
+		"wiki/w/facts/ok.md#0001":   {},
+	}}
+	_, err := vectorstore.Sync(context.Background(), brain, store, &recordingEmbedder{})
+	require.NoError(t, err)
+	assert.Equal(t, []string{"wiki/w/facts/leak.md#0001"}, store.deletes)
+}
+
+// A walk error aborts Sync before the delete pass, so chunks of files the
+// walk could not see are kept.
+func TestSyncAbortsBeforeDeletingWhenASubdirIsUnreadable(t *testing.T) {
+	if os.Geteuid() == 0 {
+		t.Skip("root ignores directory permissions")
+	}
+	brain := t.TempDir()
+	writeNote(t, brain, "wiki/w/facts/ok.md", "inside note")
+	locked := filepath.Join(brain, "wiki", "w")
+	require.NoError(t, os.Chmod(locked, 0o000))
+	t.Cleanup(func() { _ = os.Chmod(locked, 0o755) })
+	store := &stubStore{known: map[string]time.Time{"wiki/w/facts/ok.md#0001": {}}}
+	_, err := vectorstore.Sync(context.Background(), brain, store, &recordingEmbedder{})
+	assert.Error(t, err)
+	assert.Empty(t, store.deletes)
+}